Webhook Relay

Trigger an AWX Job Template from a Webhook

Trigger an AWX job template from GitHub, Bitbucket or any webhook. Filter events, map extra_vars, add bearer auth and reach a private AWX server.

AWX can launch a job template through its REST API. That makes any webhook a possible automation trigger: a Bitbucket push, a monitoring alert, an approved form submission, or an internal deployment event.

The safe pattern is to receive the source webhook, allowlist the event and branch, map only approved values into extra_vars, add an AWX API token, and then POST to /api/v2/job_templates/{id}/launch/. If AWX is private, the Webhook Relay agent delivers the request from inside its network.

When to use this pattern

Automation Controller and AWX include native webhook support for selected source-control integrations such as GitHub and GitLab. Use that built-in path when it matches your provider and workflow.

Use the job-template launch API when:

  • The sender is Bitbucket or another generic webhook provider.
  • An incident or monitoring event should run remediation.
  • You need to map a provider payload into a small set of AWX variables.
  • AWX has no public URL.
  • One event should trigger AWX and other destinations.

AWX's current API explorer documents POST /api/v2/job_templates/{id}/launch/.

Architecture

source webhook
      |
      v
Webhook Relay input
 filter + map + authenticate
      |
      | outbound relay agent
      v
private AWX /api/v2/job_templates/42/launch/

The source never receives the AWX URL or token. It only knows the stable public input URL.

1. Prepare the AWX job template

Create or select a job template and note its numeric ID from the URL or API. Run it manually once before adding a webhook.

If the webhook will provide extra_vars, configure the template to accept them through Prompt on launch or an enabled survey. Define a narrow interface such as:

  • revision
  • environment
  • service

Do not expose arbitrary playbook variables merely because they are present in the source event.

Create an AWX OAuth2 or personal access token for a service account with only the permissions required to execute this template. Store the token securely.

2. Test the AWX launch endpoint directly

From a machine that can reach AWX:

curl -i -X POST \
  https://awx.example.internal/api/v2/job_templates/42/launch/ \
  -H 'Authorization: Bearer YOUR_AWX_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"extra_vars":{"revision":"abc123","environment":"staging"}}'

Confirm AWX creates a job before introducing webhook routing. A direct test separates AWX permissions and template configuration from delivery problems.

3. Create the Webhook Relay route

Create a bucket with a public input. If AWX is public, add https://awx.example.com as a public output.

If AWX is private, set the output to its internal base URL and run:

relay forward --bucket awx https://awx.example.internal

The agent can run beside AWX, on a bastion, or in the same Kubernetes network, as long as it can resolve the hostname and validate its TLS certificate.

4. Filter and transform the webhook

This synthetic example accepts a deployment request for main or a version tag, then launches job template 42:

const event = JSON.parse(r.body)
const ref = String(event.ref || "")
const allowedRef = ref === "refs/heads/main" || /^refs\/tags\/v\d+\.\d+\.\d+$/.test(ref)

if (event.type !== "deployment.requested" || !allowedRef) {
  r.stopForwarding()
  return
}

const environment = ref.startsWith("refs/tags/") ? "production" : "staging"
const revision = String(event.revision || "")

if (!/^[a-f0-9]{7,40}$/i.test(revision)) {
  r.stopForwarding()
  return
}

const payload = {
  extra_vars: {
    revision,
    environment,
    service: "example-api",
    source_event_id: String(event.id || "")
  }
}

r.setMethod("POST")
r.setPath("/api/v2/job_templates/42/launch/")
r.setRawQuery("")
r.setHeader("Authorization", "Bearer " + cfg.get("AWX_API_TOKEN"))
r.setHeader("Content-Type", "application/json")
r.setBody(JSON.stringify(payload))

Add AWX_API_TOKEN under the function's configuration values. Attach the function to the AWX output so other outputs can still receive the original event.

Adapt the event names and fields to your provider. For GitHub or Bitbucket, filter using the provider event header and its documented push payload. The webhook filtering guide has branch and tag examples.

5. Verify the source before launching automation

Filtering a field is not authentication. Before an untrusted public request can run an AWX job:

  • Configure and verify the provider's webhook signature or secret.
  • Allowlist event types and refs.
  • Map approved fields into a new object rather than forwarding the whole body.
  • Validate revisions, inventory choices and environment names.
  • Give the AWX service account the smallest usable role.
  • Avoid accepting credentials, command fragments or playbook paths from the webhook.

For GitHub and Bitbucket HMAC examples, see how to verify a webhook signature.

6. Test and observe the launch

Send a test event and inspect both sides:

  1. Webhook Relay should show the transformed POST, AWX path and response status.
  2. AWX should create a job linked to template 42.
  3. The job's Extra Variables should contain only the mapped allowlist.
  4. A feature-branch or malformed event should be marked rejected and should not create a job.

Keep source_event_id when the provider supplies a stable ID. AWX may create another job if a webhook is retried after an ambiguous response, so use the ID in your playbook or an external lock when duplicate execution would be dangerous.

Troubleshooting

AWX returns 401 or 403

Check the token, its owner, template execute permission and the exact Authorization: Bearer ... header. Confirm the configuration value exists on the function actually attached to the output.

AWX returns 404

Verify the template ID and keep the trailing slash in /launch/. Inspect the final transformed path in the delivery log.

AWX rejects extra_vars

Open the template launch configuration and allow only the required variables through Prompt on launch or a survey. Test the same body directly with curl to see AWX's full validation response.

The relay agent cannot reach AWX

Test DNS and HTTPS from the agent host or container. Internal certificate trust, proxy configuration and split DNS are common causes. The source webhook reaching Webhook Relay only proves the public half of the route works.

The same webhook launches two jobs

Assume webhooks can be retried. Deduplicate by the provider event ID, or make the launched playbook idempotent and safe to repeat. The retries and idempotency guide covers the delivery model.

For more integrations that change method, path, headers and body, use the webhook transformation cookbook.