Webhooks
AWX Templates can be launched using webhooks. The official documentation here is not the greatest, so this page extends it.
Webhook authentication
For info about using the native implementation of Gitlab/Github webhooks, look at the official docs. This page is meant to hack the webhooks using curl.
Username + password
Below you can find the input/outputs of launching the job template number 7 using the -u flag to pass username and password for authentication.
-H 'Accept: application/json, text/plain, */*' \
-H 'Content-Type: application/json' \
--data-raw '{"extra_vars":{"file":"vault_prod.yaml"}}'
The final part passes variables to the playbook. It is similar to the -e flag when launching a playbook.
Webhook key
AWX supports Webhooks for Gitlab, Github and BitBucket. From these, the easiest to use with curl is Gitlab. Note the addition of a unique identifier, since AWX creates a hash of the body to make sure webhooks are unique
-H 'X-Gitlab-Token: secret' \
-H "Content-Type: application/json" \
--data-raw '{"extra_vars":{"file":"vault_prod.yaml", "uniq": "'$(uuidgen)'"}}'
Technically using the gitlab webhook, using extra_vars is unnecessary.
Webhook key
AWX auto-generates a key when enabling a webhook. This can be overrided by providing your own key from a Credential object. The credential types can be viewed here, more info about using webhoo
Passing variables
If no survey is set for the template, the variables passed with "--data-raw '{"extra_vars":{"file":"vault_prod.yaml"}}'" will not be passed to the playbook when using username:password authentication. See below for variables with "git webhooks"
By looking at the API definition in https://awx.web.helsinki.fi/api/v2/job_templates/7/launch/, we can see that toggling ON the survey edits the following fields
| Field name | values |
|---|---|
"can_start_without_user_input" | true: The playbook can be started without extra variables false: The playbook requires extra variables, when using a webhook these need to be passed as |
"survey_enabled" | true: when using the UI, a Survey textbox will be shown false: no textbox |
"variables_needed_to_start": | list of variables names needed for the playbook to start, e.g. ["file"] When trying to use the webhook without passing the required variable names, the server will respond with a message like |
Git webhook variables
While the username:password authenticated post to /launch places the user variables directly as variables, filling them to the survey, the Gitlab-webhook passed them in a completely different nesting. Below we are using the same playbook with both webhook types
| Username webhook | Git webhook | |
|---|---|---|
| Enforces survey required variables | Yes | No |
| Requires a unique request body | No | Yes |
| AWX has knowledge of the username | Yes | No *each template can have only a single webhook at a time |
| Needs to enabled explicitly | No | Yes |
| API url | api/v2/job_templates/<number>/launch/ | api/v2/job_templates/<number>/gitlab/ *replace gitlab with github or bitbucket where necessary |
| Curl command | curl -X POST -u username:password 'https://awx.web.helsinki.fi/api/v2/job_templates/7/launch/' \ -H 'Accept: application/json, text/plain, */*' \ -H 'Content-Type: application/json' \ --data-raw '{"extra_vars":{"file":"vault_prod.yaml"}}' | curl -X POST 'https://awx.web.helsinki.fi/api/v2/job_templates/7/gitlab/' \ -H 'X-Gitlab-Token: secret' \ -H "Content-Type: application/json" \ --data-raw '{"extra_vars":{"file":"vault_prod.yaml", "uniq": "'$(uuidgen)'"}}' |
| Variables passed to the playbook | file: '' | file: '' awx_webhook_event_type: null awx_webhook_event_guid: ea084e222fbf49e347c30fca3e459fa94c5f4419 awx_webhook_event_ref: null awx_webhook_status_api: null awx_webhook_payload: extra_vars: file: vault_prod.yaml uniq: E895F914-AD3A-4A27-8B5B-B10B9F81F224 tower_webhook_event_type: null tower_webhook_event_guid: ea084e222fbf49e347c30fca3e459fa94c5f4419 tower_webhook_event_ref: null tower_webhook_status_api: null tower_webhook_payload: extra_vars: file: vault_prod.yaml uniq: E895F914-AD3A-4A27-8B5B-B10B9F81F224 |