Notifications

AWX can send notifications about job status to various channels including email, Slack, webhooks, and more. Notifications help teams stay informed about automation activities and respond quickly to issues.

Understanding Notifications

The notification system consists of:

Notification Templates: Configured notification channels
Notification Triggers: When to send (start, success, error)
Notification Messages: Customizable content with job details
Notification Hierarchy: Inherited from organizations and projects

Notification Triggers

Started

Sent when job starts execution

Success

Sent when job completes successfully

Error/Failure

Sent when job fails or errors

Supported Notification Types

AWX supports these notification channels:

Email - SMTP email notifications
Slack - Slack channel messages
Mattermost - Mattermost webhooks
Rocket.Chat - Rocket.Chat webhooks
Pagerduty - Pagerduty incident creation
Twilio - SMS via Twilio
IRC - IRC channel messages
Webhook - Custom HTTP webhooks
Grafana - Grafana annotations

Creating Email Notifications

Create Email Notification Template

Web UI
API
Ansible

Navigate to Notification Templates
Click Add
Enter details:
- Name: Descriptive name
- Organization: Optional organization
- Type: Email
Configure email settings:
- Host: SMTP server hostname
- Port: SMTP port (25, 465, 587)
- Username: SMTP username
- Password: SMTP password
- Sender Email: From address
- Recipients: Comma-separated email list
- Use TLS: Enable for encrypted connection
Click Save

curl -X POST https://awx.example.com/api/v2/notification_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email Alerts",
    "description": "Email notifications for job failures",
    "organization": 1,
    "notification_type": "email",
    "notification_configuration": {
      "host": "smtp.example.com",
      "port": 587,
      "username": "[email protected]",
      "password": "smtp_password",
      "sender": "[email protected]",
      "recipients": ["[email protected]", "[email protected]"],
      "use_tls": true,
      "timeout": 30
    }
  }'

- name: Create email notification
  awx.awx.notification_template:
    name: Email Alerts
    description: Email notifications for job failures
    organization: Engineering
    notification_type: email
    notification_configuration:
      host: smtp.example.com
      port: 587
      username: [email protected]
      password: "{{ smtp_password }}"
      sender: [email protected]
      recipients:
        - [email protected]
        - [email protected]
      use_tls: true
    state: present

Test the Notification

Send a test notification:

curl -X POST https://awx.example.com/api/v2/notification_templates/1/test/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Or with Ansible:

- name: Test notification
  awx.awx.notification_template:
    name: Email Alerts
    notification_type: email
    test: true
    state: present

Attach to Job Template

# Attach for error notifications
curl -X POST https://awx.example.com/api/v2/job_templates/1/notification_templates_error/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

# Attach for success notifications
curl -X POST https://awx.example.com/api/v2/job_templates/1/notification_templates_success/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

# Attach for started notifications
curl -X POST https://awx.example.com/api/v2/job_templates/1/notification_templates_started/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

Slack Notifications

Integrate with Slack using bot tokens:

- name: Create Slack notification
  awx.awx.notification_template:
    name: Slack DevOps Channel
    organization: Engineering
    notification_type: slack
    notification_configuration:
      token: "{{ slack_bot_token }}"
      channels:
        - "#devops"
        - "#alerts"
    state: present

Setting up Slack

Create Slack App

Go to https://api.slack.com/apps
Click Create New App
Choose From scratch
Name your app (e.g., “AWX Notifications”)

Configure Bot Token

Go to OAuth & Permissions
Add Bot Token Scopes:
- chat:write
- chat:write.public
Install app to workspace
Copy Bot User OAuth Token

Configure AWX

Use the bot token in your notification template:

token: "xoxb-your-bot-token-here"
channels:
  - "#channel-name"

Webhook Notifications

Send custom HTTP webhooks:

- name: Create webhook notification
  awx.awx.notification_template:
    name: Custom Webhook
    organization: Engineering
    notification_type: webhook
    notification_configuration:
      url: https://example.com/webhooks/awx
      http_method: POST
      headers:
        Authorization: "Bearer {{ webhook_token }}"
        Content-Type: application/json
      disable_ssl_verification: false
    state: present

Webhook Payload

AWX sends job details in JSON format:

{
  "id": 123,
  "name": "Deploy Application",
  "url": "https://awx.example.com/#/jobs/playbook/123",
  "created_by": "admin",
  "started": "2026-01-15T10:30:00Z",
  "finished": "2026-01-15T10:35:00Z",
  "status": "successful",
  "traceback": "",
  "inventory": "Production Servers",
  "project": "Infrastructure Playbooks",
  "playbook": "deploy.yml",
  "credential": "SSH Credential",
  "limit": "webservers",
  "extra_vars": "{\"version\": \"2.0.0\"}",
  "hosts": {
    "dark": {},
    "failures": {},
    "ok": {"web01": 15, "web02": 15},
    "processed": {"web01": 1, "web02": 1},
    "skipped": {}
  }
}

Mattermost Notifications

Use incoming webhooks:

- name: Create Mattermost notification
  awx.awx.notification_template:
    name: Mattermost Alerts
    notification_type: mattermost
    notification_configuration:
      url: https://mattermost.example.com/hooks/your-webhook-id
      username: AWX Bot
      channel: devops
      icon_url: https://awx.example.com/static/media/logo-header.svg
    state: present

Mattermost Setup

Go to Main Menu → Integrations → Incoming Webhooks
Click Add Incoming Webhook
Configure:
- Display Name
- Description
- Channel (can be overridden in AWX)
Copy the webhook URL

Pagerduty Integration

Create incidents in Pagerduty:

- name: Create Pagerduty notification
  awx.awx.notification_template:
    name: Pagerduty Incidents
    notification_type: pagerduty
    notification_configuration:
      token: "{{ pagerduty_api_key }}"
      subdomain: your-subdomain
      service_key: "{{ pagerduty_service_key }}"
      client_name: AWX
    state: present

Pagerduty Setup

In Pagerduty, create a new service
Select Events API V2 integration
Copy the Integration Key (use as service_key)
Get API token from User Settings → API Access Keys

Custom Notification Messages

Customize notification content with Jinja2 templates:

curl -X POST https://awx.example.com/api/v2/notification_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Email",
    "notification_type": "email",
    "notification_configuration": {
      "host": "smtp.example.com",
      "port": 587,
      "sender": "[email protected]",
      "recipients": ["[email protected]"],
      "use_tls": true
    },
    "messages": {
      "started": {
        "message": "Job {{ job.name }} started on {{ job.inventory }}",
        "body": "Started by: {{ job.created_by }}\nPlaybook: {{ job.playbook }}"
      },
      "success": {
        "message": "Job {{ job.name }} completed successfully in {{ job.elapsed }} seconds",
        "body": "Hosts processed: {{ job.host_status_counts.ok }}\nElapsed: {{ job.elapsed }}s"
      },
      "error": {
        "message": "Job {{ job.name }} failed with status {{ job.status }}",
        "body": "{{ job.job_explanation }}\n\nCheck: {{ job.url }}"
      }
    }
  }'

Available Template Variables

Common variables for templates:

{{ job.name }}                    # Job template name
{{ job.id }}                      # Job ID
{{ job.status }}                  # Job status
{{ job.url }}                     # Job URL
{{ job.created_by }}              # User who launched
{{ job.started }}                 # Start timestamp
{{ job.finished }}                # End timestamp
{{ job.elapsed }}                 # Duration in seconds
{{ job.playbook }}                # Playbook name
{{ job.inventory }}               # Inventory name
{{ job.limit }}                   # Host limit
{{ job.extra_vars }}              # Extra variables
{{ job.job_explanation }}         # Error message
{{ job.summary_fields.instance_group.name }}  # Instance group
{{ job.host_status_counts.ok }}   # Successful hosts
{{ job.host_status_counts.failures }}  # Failed hosts
{{ job.host_status_counts.dark }}      # Unreachable hosts

Notification Hierarchy

Notifications inherit from parent resources:

Job Template Notifications

# Job template inherits from:
# 1. Job template's own notifications
# 2. Project's notifications
# 3. Organization's notifications

Workflow Notifications

# Workflow inherits from:
# 1. Workflow template's notifications
# 2. Organization's notifications

Example Hierarchy

# Organization-level (all jobs)
- name: Org-wide error notifications
  awx.awx.notification_template:
    name: Org Errors
    organization: Engineering
    notification_type: slack
    notification_configuration:
      token: "{{ slack_token }}"
      channels: ["#alerts"]
    state: present

# Attach to organization
- name: Attach to organization
  uri:
    url: "https://awx.example.com/api/v2/organizations/1/notification_templates_error/"
    method: POST
    headers:
      Authorization: "Bearer {{ awx_token }}"
    body_format: json
    body:
      id: 1

# Project-level (specific project jobs)
- name: Project notifications
  awx.awx.notification_template:
    name: Project Alerts
    notification_type: email
    notification_configuration:
      recipients: ["[email protected]"]
    state: present

# Job template-level (specific job)
- name: Job-specific notifications
  awx.awx.notification_template:
    name: Critical Job Alerts
    notification_type: pagerduty
    notification_configuration:
      service_key: "{{ pagerduty_key }}"
    state: present

Attaching Notifications

To Job Templates

# Attach for failures
- name: Attach error notification to job template
  uri:
    url: "https://awx.example.com/api/v2/job_templates/1/notification_templates_error/"
    method: POST
    headers:
      Authorization: "Bearer {{ awx_token }}"
    body_format: json
    body:
      id: 1

# Attach for success
- name: Attach success notification
  uri:
    url: "https://awx.example.com/api/v2/job_templates/1/notification_templates_success/"
    method: POST
    headers:
      Authorization: "Bearer {{ awx_token }}"
    body_format: json
    body:
      id: 2

To Projects

# Project update notifications
curl -X POST https://awx.example.com/api/v2/projects/1/notification_templates_error/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

To Organizations

# Organization-wide notifications
curl -X POST https://awx.example.com/api/v2/organizations/1/notification_templates_error/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

To Workflows

curl -X POST https://awx.example.com/api/v2/workflow_job_templates/1/notification_templates_error/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

Notification Status

View notification history:

# List all notifications
curl https://awx.example.com/api/v2/notifications/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# View specific notification
curl https://awx.example.com/api/v2/notifications/123/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Notifications for a job
curl https://awx.example.com/api/v2/jobs/456/notifications/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Notification statuses:

pending: Queued for sending
successful: Sent successfully
failed: Failed to send

Advanced Configurations

Multiple Recipients

notification_configuration:
  recipients:
    - [email protected]
    - [email protected]
    - [email protected]

Conditional Notifications

Use different notifications for different job templates:

# Critical jobs - Pagerduty
- name: Critical job notifications
  awx.awx.notification_template:
    name: Critical Alerts
    notification_type: pagerduty
    state: present

# Regular jobs - Slack
- name: Regular job notifications
  awx.awx.notification_template:
    name: Regular Alerts
    notification_type: slack
    state: present

Rate Limiting

AWX does not have built-in rate limiting for notifications. Consider:

External notification aggregation
Webhook endpoints that handle deduplication
Scheduled summary reports instead of per-job notifications

Troubleshooting

Email notifications not sending

Check:

SMTP credentials are correct
SMTP port is accessible from AWX (telnet test)
TLS/SSL settings match server requirements
Firewall allows outbound SMTP

Test notification:

curl -X POST https://awx.example.com/api/v2/notification_templates/1/test/ \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check notification result
curl https://awx.example.com/api/v2/notifications/?notification_template=1 \
  -H "Authorization: Bearer YOUR_TOKEN" | jq -r '.results[0]'

Slack notifications failing

Verify:

Bot token is correct and starts with xoxb-
Bot has chat:write permission
Channel name includes # (e.g., #devops)
Bot is invited to private channels

Test with curl:

curl -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer YOUR_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel": "#devops", "text": "Test"}'

Webhook notifications returning errors

Debug:

Check webhook URL is accessible
Verify authentication headers
Review webhook endpoint logs
Test with curl:

curl -X POST https://your-webhook-url.com/endpoint \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test": "message"}'

Notifications not triggering

Verify:

Notification template is attached to the resource
Correct trigger type (started/success/error)
Notification template is enabled

List attached notifications:

# For job template errors
curl https://awx.example.com/api/v2/job_templates/1/notification_templates_error/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Best Practices

Use Hierarchy

Set organization-level notifications for common alerts, job-level for specific needs

Test First

Always test notification templates before attaching to production jobs

Customize Messages

Use custom messages to provide relevant context and actionable information

Monitor Delivery

Regularly check notification history to ensure delivery success

Job Templates

Create jobs that trigger notifications

Workflows

Configure notifications for workflows

Scheduling

Combine schedules with notifications for automated monitoring

Notification API

Complete API reference for notifications

Overview

Installation

Core Concepts

User Guide

Advanced Features

Integrations

Administration

​Understanding Notifications

​Notification Triggers

Started

Success

Error/Failure

​Supported Notification Types

​Creating Email Notifications

​Slack Notifications

​Setting up Slack

​Webhook Notifications

​Webhook Payload

​Mattermost Notifications

​Mattermost Setup

​Pagerduty Integration

​Pagerduty Setup

​Custom Notification Messages

​Available Template Variables

​Notification Hierarchy

​Job Template Notifications

​Workflow Notifications

​Example Hierarchy

​Attaching Notifications

​To Job Templates

​To Projects

​To Organizations

​To Workflows

​Notification Status

​Advanced Configurations

​Multiple Recipients

​Conditional Notifications

​Rate Limiting

​Troubleshooting

​Best Practices