Webhook

A Webhook is a custom callback URL that can be registered with an external service (e.g. Slack, GitHub) to receive events. Webhooks are typically defined for triggering Jobs.

A Webhook is an org-level resource and must be managed by org admins. Individual members may define personal Jobs that are triggered by a defined Webhook, subject to the access control policy defined in the webhook.

Basics

A Webhook is defined by specifying a path, which produces a full URL of the form:

https://SYS-DOMAIN/webhook/orgs/ORG/PATH

where SYS-DOMAIN and ORG come from the deployment, and PATH is the path specified by the webhook. The path may contain more than one component, separated by /.

Delivery ID

Usually, a dedicated header carries the delivery ID, which uniquely identifies the event. It is used by the retry mechanism (redelivery of the event) and to avoid duplicates. This header can be specified explicitly with delivery_id_header in the definition. If unspecified, the following well-known headers are tried, in order:

X-GitHub-Delivery
X-Request-Id
X-Delivery-Id
X-Event-Id
X-Webhook-Id

Response Status

Normally, status 200 is returned on a successful delivery (that is, when the system is able to trigger the associated Jobs). This can be overridden with success_status in the definition.

Payload Size

To prevent attacks, the system only accepts a limited payload size from the request. If the default limit is too small, body_limit can be used to specify a reasonable limit.

Filtering

Additional filtering can be defined to exclude irrelevant webhook events when this can't be configured in the source service.

Header Matching

header_regexp:
  Header1: Value-Regexp
  Header2: Value-Regexp

A list of header/value matching conditions can be specified, where the values are regular expressions.

HMAC Signature Verification

This is commonly used by services like GitHub (using a webhook secret). For example:

hmac:
  hash: sha256
  secret: SECRET
  header: X-Hub-Signature-256

Custom Script

A custom script (CEL or Go template) can be used for more complex filtering against the whole event:

filter:
  language: cel
  script: |
    "x-my-key" in event.headers && event.headers["x-my-key"] == "expected"

The output of the script (true, or a non-empty value for non-boolean results) determines whether the event is handled.

Event Schema

When passed to a filter or transform script, or used for rendering templates, the event context contains the following fields:

event, which contains:
headers — a map of HTTP header/value pairs.
body — present if the request contains a JSON or form-encoded payload; this is the decoded object.
raw_body — the original, undecoded payload, as a string.

Access Control

A Webhook is an org-level resource managed by org admins, and it contains a policy defining who can associate Jobs to be triggered by the webhook:

access_control:
  sharing_mode: EXPLICIT
  explicit_users:
  - foo@bar.com
  - tag:job-subscribers

The sharing_mode defines who can associate Jobs:

DEFAULT — only admins can. The webhook is used only at the org level, not for members' personal automations.
EXPLICIT — in addition to admins, only the users listed in explicit_users can.
SHARED — anyone in the org can.