Webhooks - AWX

Webhooks enable external systems like GitHub, GitLab, and Bitbucket to automatically trigger AWX jobs in response to events such as code pushes, pull requests, and releases.

Overview

AWX supports webhook integration for:

GitHub - GitHub.com and GitHub Enterprise
GitLab - GitLab.com and self-hosted GitLab
Bitbucket Data Center - Self-hosted Bitbucket

Webhooks provide a secure way to trigger automation based on repository events without polling or manual intervention.

Webhook Components

Webhook Key

Each Job Template and Workflow Job Template can have an associated webhook key:

Secret token used to validate incoming webhook requests
Automatically generated when webhook service is enabled
Can be rotated for security

Webhook Service

Specifies which external service sends the webhook:

github
gitlab
bitbucket_dc

Webhook Credential

Optional credential for authenticating back to the external service:

Used to post status updates
Enables AWX to update commit statuses

Configuration

Step 1: Enable Webhooks on Template

Configure a Job Template or Workflow Job Template for webhook support:

curl -X PATCH https://awx.example.com/api/v2/job_templates/42/ \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_service": "github",
    "webhook_credential": 15
  }'

Set Webhook Service

Choose github, gitlab, or bitbucket_dc

Configure Credential (Optional)

Associate a credential for status updates

Save Template

Webhook key is automatically generated

Step 2: Retrieve Webhook Key

Get the webhook key for configuring the external service:

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

Response:

{
  "webhook_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Store the webhook key securely. It’s required to configure the external service and validates incoming webhook requests.

Step 3: Configure External Service

Set up the webhook in your repository:

GitHub

Navigate to Repository Settings

Go to Settings → Webhooks → Add webhook

Configure Webhook URL

https://awx.example.com/api/v2/job_templates/42/github/

Or for workflows:

https://awx.example.com/api/v2/workflow_job_templates/15/github/

Set Content Type

Select application/json

Add Secret

Paste the webhook key from AWX

Choose Events

Select events that should trigger jobs (push, pull_request, etc.)

GitLab

Navigate to Repository Settings

Go to Settings → Webhooks

Configure Webhook URL

https://awx.example.com/api/v2/job_templates/42/gitlab/

Add Secret Token

Paste the webhook key from AWX

Select Triggers

Choose events (Push events, Merge request events, etc.)

Disable SSL Verification (if needed)

Only for self-signed certificates in non-production

Bitbucket Data Center

Navigate to Repository Settings

Go to Repository settings → Webhooks → Create webhook

Configure Webhook URL

https://awx.example.com/api/v2/job_templates/42/bitbucket_dc/

Set Secret

Paste the webhook key from AWX

Choose Events

Select triggers (Repository push, Pull request opened, etc.)

Webhook Behavior

Request Processing

When a webhook is received:

Signature Verification

AWX validates the webhook signature using the webhook key

Duplicate Detection

Checks if this webhook GUID has already been processed

Event Extraction

Extracts event type, GUID, ref (branch/tag/commit), and status API URL

Job Creation

Creates a new job with webhook metadata

Job Launch

Queues and starts the job

Signature Verification

Each webhook service uses different signature methods: GitHub:

Header: X-Hub-Signature
Algorithm: HMAC SHA-1
Format: sha1=<signature>

GitLab:

Header: X-Gitlab-Token
Algorithm: Direct token comparison (no HMAC)
Format: Plain text token

Bitbucket Data Center:

Header: X-Hub-Signature
Algorithm: HMAC SHA-256 or SHA-1
Format: sha256=<signature> or sha1=<signature>
Ping requests are not signed

All webhook requests are rejected if signature verification fails. Ensure the webhook key matches on both sides.

Webhook Variables

Webhook events provide extra variables to your playbooks:

awx_webhook_event_type: "push"
awx_webhook_event_guid: "12345678-1234-1234-1234-123456789abc"
awx_webhook_event_ref: "a1b2c3d4e5f6"
awx_webhook_status_api: "https://api.github.com/repos/owner/repo/statuses/a1b2c3d4e5f6"
awx_webhook_payload:
  ref: "refs/heads/main"
  repository:
    name: "my-repo"
    full_name: "owner/my-repo"
  commits:
    - id: "a1b2c3d4e5f6"
      message: "Update deployment config"

All variables are prefixed with awx_, tower_, and ansible_ for compatibility. Use awx_* variables in new playbooks.

Using Webhook Variables

- name: Deploy application on push
  hosts: webservers
  tasks:
    - name: Show webhook info
      debug:
        msg: |
          Event: {{ awx_webhook_event_type }}
          Branch: {{ awx_webhook_payload.ref }}
          Commit: {{ awx_webhook_event_ref }}
          Author: {{ awx_webhook_payload.commits[0].author.name }}

    - name: Clone repository at specific commit
      git:
        repo: "{{ awx_webhook_payload.repository.clone_url }}"
        dest: /var/www/app
        version: "{{ awx_webhook_event_ref }}"

Event Types and References

GitHub Events

Supported event types and their reference keys:

Event Type	Event Ref (Commit/Tag)
`push`	`after` (commit SHA)
`pull_request`	`pull_request.head.sha`
`pull_request_review`	`pull_request.head.sha`
`pull_request_review_comment`	`pull_request.head.sha`
`release`	`release.tag_name`
`commit_comment`	`comment.commit_id`
`create`	`ref` (branch or tag name)
`page_build`	`build.commit`

GitLab Events

Supported event types and their reference keys:

Event Type	Event Ref (Commit/Tag)
`Push Hook`	`checkout_sha`
`Tag Push Hook`	`checkout_sha`
`Merge Request Hook`	`object_attributes.last_commit.id`

Bitbucket Data Center Events

Supported event types and their reference keys:

Event Type	Event Ref (Commit/Tag)
`repo:refs_changed`	`changes.0.toHash`
`mirror:repo_synchronized`	`changes.0.toHash`
`pr:opened`	`pullRequest.toRef.latestCommit`
`pr:from_ref_updated`	`pullRequest.toRef.latestCommit`
`pr:modified`	`pullRequest.toRef.latestCommit`

Bitbucket Data Center ignores other event types. Only the events listed above trigger jobs.

Security

Webhook Key Rotation

Rotate the webhook key if compromised:

curl -X POST \
  https://awx.example.com/api/v2/job_templates/42/webhook_key/ \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "webhook_key": "z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0"
}

After rotating the key, update the webhook configuration in your external service immediately. Old key will no longer work.

Permissions

Webhook key management requires:

Get webhook key: Admin role on the template
Rotate webhook key: Admin role on the template

Webhook receivers:

Use AllowAny permission (no authentication required)
Security provided by signature verification
Invalid signatures are rejected with 403 Forbidden

Best Practices

Use HTTPS

Always use HTTPS URLs for webhook endpoints to prevent interception

Rotate Keys

Periodically rotate webhook keys as part of security policy

Limit Events

Configure only necessary events to reduce noise and processing

Monitor Logs

Review webhook logs for suspicious activity or failures

Status Updates

When a webhook credential is configured, AWX can post status updates back to the repository.

GitHub Status Updates

POST {{ awx_webhook_status_api }}
{
  "state": "success",
  "target_url": "https://awx.example.com/#/jobs/playbook/123",
  "description": "AWX job completed successfully",
  "context": "continuous-integration/awx"
}

Status appears on commits and pull requests in GitHub UI.

GitLab Status Updates

POST {{ awx_webhook_status_api }}
{
  "state": "success",
  "target_url": "https://awx.example.com/#/jobs/playbook/123",
  "description": "AWX job completed successfully",
  "name": "awx-job-template"
}

Bitbucket Status Updates

POST {{ awx_webhook_status_api }}
{
  "state": "SUCCESSFUL",
  "key": "awx-job-template-42",
  "name": "AWX Job Template",
  "url": "https://awx.example.com/#/jobs/playbook/123",
  "description": "Job completed successfully"
}

Troubleshooting

Webhook Not Triggering Jobs

Verify Webhook URL

Ensure the URL matches the pattern exactly:

/api/v2/{job_templates|workflow_job_templates}/<id>/{github|gitlab|bitbucket_dc}/

Check Webhook Key

Verify the key in the external service matches AWX

Review External Service Logs

Check webhook delivery logs in GitHub/GitLab/Bitbucket

Examine AWX Logs

Look for webhook-related errors in AWX logs:

docker logs awx_task | grep webhook

Signature Verification Failures

Common causes:

Webhook key mismatch between AWX and external service
Wrong webhook service type configured (e.g., github vs gitlab)
Network proxy modifying request body
Incorrect Content-Type header

Duplicate Webhook Detection

If webhooks are being ignored:

AWX tracks webhook GUIDs to prevent duplicate processing
Redelivering the same webhook from the external service will be ignored
This is normal behavior to prevent duplicate job runs
Create a new event to trigger a new job

Jobs Not Using Correct Ref

Ensure your Job Template is configured correctly:

Project must support SCM branch override
Job Template must have “Prompt on launch” enabled for SCM branch
Use {{ awx_webhook_event_ref }} to checkout the correct ref

Use Cases

Continuous Deployment

Configure Webhook on Main Branch

Set up webhook to trigger on push events to main branch

Create Deployment Job Template

Job template runs deployment playbook

Automatic Deployments

Every push to main triggers deployment automatically

Pull Request Testing

- name: Run tests on PR
  hosts: test_servers
  tasks:
    - name: Checkout PR branch
      git:
        repo: "{{ awx_webhook_payload.pull_request.head.repo.clone_url }}"
        dest: /tmp/test-{{ awx_webhook_event_guid }}
        version: "{{ awx_webhook_event_ref }}"

    - name: Run test suite
      command: pytest /tmp/test-{{ awx_webhook_event_guid }}/tests

Multi-Environment Deployments

Use different templates for different branches:

main branch → Production deployment
staging branch → Staging deployment
develop branch → Development deployment

Configure branch filters in your webhook or use conditional logic in playbooks.

API Reference

Get Webhook Key

GET /api/v2/{job_templates|workflow_job_templates}/<id>/webhook_key/

Rotate Webhook Key

POST /api/v2/{job_templates|workflow_job_templates}/<id>/webhook_key/

Webhook Receivers

POST /api/v2/job_templates/<id>/github/
POST /api/v2/job_templates/<id>/gitlab/
POST /api/v2/job_templates/<id>/bitbucket_dc/

POST /api/v2/workflow_job_templates/<id>/github/
POST /api/v2/workflow_job_templates/<id>/gitlab/
POST /api/v2/workflow_job_templates/<id>/bitbucket_dc/

Webhook receiver endpoints do not require authentication. Security is provided by signature verification using the webhook key.

​Overview

​Webhook Components

​Webhook Key

​Webhook Service

​Webhook Credential

​Configuration

​Step 1: Enable Webhooks on Template

​Step 2: Retrieve Webhook Key

​Step 3: Configure External Service

​GitHub

​GitLab

​Bitbucket Data Center

​Webhook Behavior

​Request Processing

​Signature Verification

​Webhook Variables

​Using Webhook Variables

​Event Types and References

​GitHub Events

​GitLab Events

​Bitbucket Data Center Events

​Security

​Webhook Key Rotation

​Permissions

​Best Practices

Use HTTPS

Rotate Keys

Limit Events

Monitor Logs

​Status Updates

​GitHub Status Updates

​GitLab Status Updates

​Bitbucket Status Updates

​Troubleshooting

​Webhook Not Triggering Jobs

​Signature Verification Failures

​Duplicate Webhook Detection

​Jobs Not Using Correct Ref

​Use Cases

​Continuous Deployment

​Pull Request Testing

​Multi-Environment Deployments

​API Reference

​Get Webhook Key

​Rotate Webhook Key

​Webhook Receivers

Overview

Webhook Components

Webhook Key

Webhook Service

Webhook Credential

Configuration

Step 1: Enable Webhooks on Template

Step 2: Retrieve Webhook Key

Step 3: Configure External Service

GitHub

GitLab

Bitbucket Data Center

Webhook Behavior

Request Processing

Signature Verification

Webhook Variables

Using Webhook Variables

Event Types and References

GitHub Events

GitLab Events

Bitbucket Data Center Events

Security

Webhook Key Rotation

Permissions

Best Practices

Status Updates

GitHub Status Updates

GitLab Status Updates

Bitbucket Status Updates

Troubleshooting

Webhook Not Triggering Jobs

Signature Verification Failures

Duplicate Webhook Detection

Jobs Not Using Correct Ref

Use Cases

Continuous Deployment

Pull Request Testing

Multi-Environment Deployments

API Reference

Get Webhook Key

Rotate Webhook Key

Webhook Receivers