Connect webhooks and prove you own a site

Send this workspace's news to Slack, Teams or your own service, and prove a site is yours so heavy tests may run against it.

In short

A webhook posts a short, signed message to Slack, Microsoft Teams or your own service when something happens in your workspace. A verified site proves a site is yours, so heavy tests such as load tests may run against it.

Before you start

Who: in your Personal Workspace you do everything. In an organization only people who manage its settings see and change its webhooks and verified sites.
Plan: a workspace keeps up to 20 webhooks. Load tests need a plan with load testing.
First: an https address from Slack, Teams or your service. To prove a site, you must be able to put a file or a header on it.

Add a webhook

Open Settings › "Webhooks" and press "Add a webhook".
Type a "Name", such as Releases channel, and the https "Address" the receiver gave you.
Choose a "Format": "Generic JSON" for your own service, "Slack" or "Microsoft Teams" for a channel.
Under "Also send when", tick the workspace events it should hear of - a card finished, an application came in, a member joined. You can change them later with "Edit".
Press "Add webhook". Copy the signing secret with "Copy secret" - it is not shown again - and press "Done".
Press "Send a test", then "Open the log" to see it arrive with the answer's status code and time.

Prove you own a site

Open Settings › "Verified sites" and press "Prove a site".
Type the "Site address" heavy tests will use, such as https://api.example.com, and press "Get a token".
Put the token on the site in one of two ways. With "Serve a file", the address shown answers with the token as its whole text. With "Or send a header", the site's root page answers with the header shown.
Press "Verify now". The card says "Verified" and "Verified until".

The signing secret

Every message carries a signature header - its name is on the dialog that shows the secret - holding t=<time>,v1=<HMAC-SHA256 of "<time>.<body>">, made with the webhook's signing secret. The receiver recomputes it and refuses a message whose signature differs or whose time is more than a few minutes old. "Replace signing secret" asks what happens to the old one: "Keep it for a day" signs every message with both secrets for 24 hours - a second v1 value - so the receiver can switch over without refusing one; "Stop it now" ends the old one at once, for a secret that leaked. The webhook's row says until when the old one still signs.

Send a failed message again

Open the webhook's "Delivery log". A message that failed after every retry shows "Failed".
Press "Send again" on its row, or "Send failed messages again" above the log for all of them.
Each goes again under its own delivery id, so a receiver that drops repeats handles it once. A failed message can be sent again for 30 days, while the webhook is on.

Good to know

A workspace keeps up to 20 webhooks. {{brand}} never sends to private or local networks.
The switch turns a webhook off and on. {{brand}} switches one off by itself when it answers 410 Gone or its last deliveries all failed. It says why on the row.
In an organization only people who manage its settings see its webhooks and proved sites. Your personal workspace's are yours alone.
A proof covers that host and port only. It lapses 30 days after its last check: keep the token on the site and press "Verify again". Sites on private networks can never be proved.

If something goes wrong

"Use an address that starts with https://.": webhooks send only to https addresses.
"This workspace has 20 webhooks, the most it can keep. Remove one to add another."
"Turn the webhook on to send a test.": switch it on first.
"{site} is not verified yet - the card says what was missing.": read "Last check" on the card, fix the file or header, and verify again.
"Only the people who manage {organization} see its webhooks": ask an organization admin, or switch to your personal workspace.

/help/settings/integrations
/help/settings/access-tokens
/help/api-testing/load-testing
/help/boards/board-webhooks-and-repositories