Notifications

Overview

Notifications enable AWX to send alerts about job status, workflow completion, and other events to external services. Notifications are configured via notification templates and can be associated with jobs, projects, and workflows.

Notification Templates

Endpoints

Method	Endpoint	Description
GET	`/api/v2/notification_templates/`	List notification templates
POST	`/api/v2/notification_templates/`	Create notification template
GET	`/api/v2/notification_templates/{id}/`	Retrieve template
PATCH	`/api/v2/notification_templates/{id}/`	Update template
DELETE	`/api/v2/notification_templates/{id}/`	Delete template
POST	`/api/v2/notification_templates/{id}/test/`	Test notification

List Notification Templates

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

Create Notification Template

Slack Notification

curl -X POST \
  https://awx.example.com/api/v2/notification_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alerts",
    "description": "Send alerts to Slack",
    "organization": 1,
    "notification_type": "slack",
    "notification_configuration": {
      "token": "xoxb-your-slack-token",
      "channels": ["#ansible-alerts"]
    }
  }'

Email Notification

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": "Send email notifications",
    "organization": 1,
    "notification_type": "email",
    "notification_configuration": {
      "host": "smtp.example.com",
      "port": 587,
      "username": "notifications@example.com",
      "password": "smtp_password",
      "use_tls": true,
      "use_ssl": false,
      "sender": "AWX <notifications@example.com>",
      "recipients": ["team@example.com"]
    }
  }'

Webhook Notification

curl -X POST \
  https://awx.example.com/api/v2/notification_templates/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Webhook Alert",
    "organization": 1,
    "notification_type": "webhook",
    "notification_configuration": {
      "url": "https://example.com/webhook",
      "http_method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer webhook-token"
      }
    }
  }'

string

required

Notification template name

string

Template description

integer

required

Organization ID

string

required

Notification type: email, slack, twilio, pagerduty, webhook, mattermost, rocketchat, irc, grafana

object

required

Configuration specific to notification type

Test Notification

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

Sends a test notification to verify configuration.

Notification Types

Email

{
  "notification_type": "email",
  "notification_configuration": {
    "host": "smtp.gmail.com",
    "port": 587,
    "username": "user@gmail.com",
    "password": "app_password",
    "use_tls": true,
    "sender": "AWX <awx@example.com>",
    "recipients": ["team@example.com", "alerts@example.com"]
  }
}

Slack

{
  "notification_type": "slack",
  "notification_configuration": {
    "token": "xoxb-slack-bot-token",
    "channels": ["#ops", "#alerts"],
    "hex_color": "#FF0000"
  }
}

PagerDuty

{
  "notification_type": "pagerduty",
  "notification_configuration": {
    "token": "pagerduty-integration-key",
    "subdomain": "mycompany",
    "service_key": "service-api-key",
    "client_name": "AWX"
  }
}

Webhook

{
  "notification_type": "webhook",
  "notification_configuration": {
    "url": "https://api.example.com/webhook",
    "http_method": "POST",
    "headers": {
      "Authorization": "Bearer token",
      "Content-Type": "application/json"
    },
    "disable_ssl_verification": false
  }
}

Mattermost

{
  "notification_type": "mattermost",
  "notification_configuration": {
    "url": "https://mattermost.example.com/hooks/webhook-id",
    "username": "AWX",
    "channel": "ansible",
    "icon_url": "https://example.com/awx-icon.png"
  }
}

Associate Notifications with Resources

Job Template Notifications

Started Notifications

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

Success Notifications

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

Error Notifications

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

Workflow Template Notifications

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

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

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

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

Organization Notifications

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

Project Notifications

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

Notifications

List Notifications

Get notification history:

curl -X GET \
  https://awx.example.com/api/v2/notifications/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieve Notification

curl -X GET \
  https://awx.example.com/api/v2/notifications/123/ \
  -H "Authorization: Bearer YOUR_TOKEN"

integer

Notification ID

string

Status: pending, successful, failed

string

Error message if failed

integer

Number of notifications sent

string

Type of notification

string

Notification recipients

string

Notification subject/title

object

Notification message body

Job Notifications

curl -X GET \
  https://awx.example.com/api/v2/jobs/123/notifications/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Notification Messages

Notification messages include job/workflow details:

{
  "id": 123,
  "name": "Deploy Application",
  "url": "https://awx.example.com/#/jobs/playbook/123",
  "created_by": "admin",
  "started": "2024-01-15T10:30:00Z",
  "finished": "2024-01-15T10:35:00Z",
  "status": "successful",
  "traceback": "",
  "inventory": "Production",
  "project": "Ansible Playbooks",
  "playbook": "site.yml",
  "credential": "AWS Production",
  "limit": "web*",
  "extra_vars": "{\"env\": \"production\"}",
  "hosts": {
    "ok": 5,
    "changed": 3,
    "dark": 0,
    "failures": 0,
    "skipped": 1
  }
}

Filtering

# By notification template
?notification_template=5

# By status
?status=failed

# By type
?notification_type=slack

# By date
?created__gte=2024-01-01

Complete Example

import requests
import json

base_url = "https://awx.example.com/api/v2"
token = "YOUR_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Create Slack notification template
slack_template = {
    "name": "Production Alerts",
    "description": "Send alerts to production Slack channel",
    "organization": 1,
    "notification_type": "slack",
    "notification_configuration": {
        "token": "xoxb-your-token",
        "channels": ["#production-alerts"],
        "hex_color": "#FF0000"
    }
}

response = requests.post(
    f"{base_url}/notification_templates/",
    headers=headers,
    data=json.dumps(slack_template)
)

if response.status_code == 201:
    template = response.json()
    template_id = template['id']
    print(f"Created notification template {template_id}")
    
    # Test notification
    test_response = requests.post(
        f"{base_url}/notification_templates/{template_id}/test/",
        headers=headers
    )
    
    if test_response.status_code == 200:
        print("Test notification sent successfully")
    
    # Associate with job template (error notifications)
    job_template_id = 10
    assoc_response = requests.post(
        f"{base_url}/job_templates/{job_template_id}/notification_templates_error/",
        headers=headers,
        data=json.dumps({"id": template_id})
    )
    
    if assoc_response.status_code == 204:
        print(f"Associated with job template {job_template_id}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

Getting Started

Core Resources

Job Management

Advanced

Notifications

Overview

Notification Templates

Endpoints

List Notification Templates

Create Notification Template

Slack Notification

Email Notification

Webhook Notification

Test Notification

Notification Types

Email

Slack

PagerDuty

Webhook

Mattermost

Associate Notifications with Resources

Job Template Notifications

Started Notifications

Success Notifications

Error Notifications

Workflow Template Notifications

Organization Notifications

Project Notifications

Notifications

List Notifications

Retrieve Notification

Job Notifications

Notification Messages

Filtering

Complete Example

​Overview

​Notification Templates

​Endpoints

​List Notification Templates

​Create Notification Template

​Slack Notification

​Email Notification

​Webhook Notification

​Test Notification

​Notification Types

​Email

​Slack

​PagerDuty

​Webhook

​Mattermost

​Associate Notifications with Resources

​Job Template Notifications

​Started Notifications

​Success Notifications

​Error Notifications

​Workflow Template Notifications

​Organization Notifications

​Project Notifications

​Notifications

​List Notifications

​Retrieve Notification

​Job Notifications

​Notification Messages

​Filtering

​Complete Example

Overview

Notification Templates

Endpoints

List Notification Templates

Create Notification Template

Slack Notification

Email Notification

Webhook Notification

Test Notification

Notification Types

Email

Slack

PagerDuty

Webhook

Mattermost

Associate Notifications with Resources

Job Template Notifications

Started Notifications

Success Notifications

Error Notifications

Workflow Template Notifications

Organization Notifications

Project Notifications

Notifications

List Notifications

Retrieve Notification

Job Notifications

Notification Messages

Filtering

Complete Example