Links

Webhooks

Your application can use webhooks to subscribe to events happening on your Aviator account.
When configuring a webhook, you can use the UI to choose which event actions will send you payloads. Only subscribing to the specific events you plan on handling limits the number of HTTP requests to your server. You can also subscribe to all current and future event actions. You can change the list of subscribed events anytime.
Each event corresponds to a certain set of actions that can happen on your organization’s repository. For example, if you subscribe to the merge failure event you'll receive detailed payloads every time a PR fails to merge.

PullRequest events

Payload

Each PullRequest webhook event payload contains the following properties.
Key
Description
action
All webhook payloads contain an action property that contains the specific activity that triggered the event.
repository
Name of GitHub repository associated with the action.
organization
Name of the GitHub organization associated with the action.
pr_number
Integer. PR Number associated with the action.
author
GitHub handle of the author of the PR.
status
Current status of the PR. Valid options: open, pending, queued, blocked, merged
skip_line
Boolean. Represents whether the skip line label is present for the PR.
status_code
Integer. Represents the reason for failure, if there was a failure. See Status Codes section for all possible options.
status_code_text
String. Represents the reason for failure, if there was a failure. See Status Codes section for all possible options.
message
Optional. Present if there is an additional message provided by GitHub on the reason for failure.
failed_ci_list
Optional. List. List of CI names that failed in case of CI failure.
pr_reset_count
Optional. Integer. Number of PRs that were reset due to a reset. This property only exists during a reset action.

Actions

Below is the list of actions that can be configured in the MQ UI to receive webhook events.
Name
When it is triggered
opened
When the PR is opened.
labeled
When the Aviator trigger label was added to a PR.
queued
When the PR is queued. This typically happens when the PR is in an approved state and the Aviator trigger label is associated with the PR.
dequeued
When the Aviator label is manually removed from the PR. It is not reported in case of PR failing to merge.
top_of_queue
When the PR reaches the top of the queue for processing.
merged
When the PR is successfully merged.
blocked
When the PR fails to merge and is blocked. The typical reason for failures can be retrieved from status_code, including CI failure or merge conflict.
stuck
(Parallel mode only) When a PR is stuck if the original PR is still running the checks after the specified timeout.
reset
(Parallel mode only) When a parallel PR queue is reset.

Batch events

Batch events contain one or more PullRequests that are queued together in a single batch. These events are triggered regardless of configured batch_size.

Payload

Key
Description
action
All webhook payloads contain an action property that contains the specific activity that triggered the event.
repository
Name of GitHub repository associated with the action.
organization
Name of the GitHub organization associated with the action.
pull_requests
A list of pull_requests associated with the batch. Each pull_request object contains pr_number, author, status, skip_line, status_code
message
Optional. Present if there is an additional message provided by GitHub on the reason for failure.

Actions

Name
When it's triggered
batch_merged
When a batch of PRs are merged.
batch_failed
When a batch failed to merge.

Webhook Signatures

All webhooks sent by Aviator include a digest signature to verify that the webhook was sent by Aviator itself. The signature is included in a X-Aviator-Signature-SHA256 header and is calculated as the SHA256 of the webhook body using the Aviator account API token as the HMAC key.
In Python, this can be calculated as follows.
compare_signature.py
# The exact HTTP body of the webhook
message_body = "{...}"
# The Aviator API token associated with the account
api_token = "av_live_xxxyyyzzz"
# The signature received in the headers of the webhook request
received_signature = "bbbf25d449dc5f1101d36085b7913dfccce6a9307048ed110d4c70afd83eafd5"
import hashlib
import hmac
signature = hmac.new(
api_token.encode(), message_body.encode(), hashlib.sha256
).hexdigest()
# Use compare_digest rather than == to prevent timing attacks.
if hmac.compare_digest(received_signature, signature):
print("Signatures match!")
else:
raise ValueError("Signatures do not match!")