Release webhooks: which events to send, how to verify them, how to retry
A webhook tells another system that something happened: a release merged, a deploy failed, a revert finished. They are how a release tool talks to PagerDuty, chat, dashboards and your own scripts without anyone polling. Done badly they are noisy, spoofable or silently lost, so here is what to get right.
Events worth sending
- Scheduled and cancelled: so a calendar or dashboard stays accurate.
- Merged: the moment code reached the branch.
- Deploy succeeded: the thing most people actually want to know.
- Deploy failed, revert started and reverted: the ones to alert on, with the failed step in the message. A revert-started event is also the moment to run your own rollback, such as a down-migration.
- Needs attention: automation could not finish, so a person must look. This is the event to wake someone for.
What to put in the message
- An id and a type, so receivers can route and de-duplicate.
- The repository, pull request, status, and links to the pull request, the deploy run and the revert.
- For failures: the workflow, job and step that failed.
- Nothing secret and no source code.
Signing and verifying
Anyone who finds your endpoint address can post to it, so check every call. The common scheme (Standard Webhooks) sends an id, a timestamp and a signature: the base64 HMAC-SHA256 of the id, the timestamp and the raw body, keyed with a shared secret. The receiver recomputes it from the raw body and compares in constant time. It also rejects timestamps more than a few minutes old, so a captured call cannot be replayed later.
Retries and duplicates
- Answer with any 2xx quickly, and do the slow work afterwards.
- Senders should retry with growing gaps, for example after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, and stop after a few tries.
- Retries repeat the same message id. Receivers should store ids they have seen and ignore duplicates.
- Switch off an endpoint that has failed for days, and tell its owner.
Keeping the sender safe
A webhook makes your server call an address that someone else typed in. Allow https only, resolve the name and refuse private, loopback and cloud-metadata addresses before connecting, do not follow redirects, set a short timeout, and cap the size of what you send.
What Merge Scheduler sends
On Pro and Team, add endpoints in Settings, Webhooks, or through the API. It sends release.scheduled, release.cancelled, release.skipped, release.merged, release.deploy_succeeded, release.deploy_failed, release.reverting, release.reverted, release.needs_attention and release.failed, signed as described above, with the retry schedule listed. There is a test button, a list of recent deliveries, and examples for verifying in Node and Python in the API docs.
Do this in Merge Scheduler: Get email, Slack and Discord alerts for every release · Schedule merges from the API or an AI assistant
Related: How to let an AI assistant schedule your GitHub merges, safely · How to automatically revert a failed deploy (and when not to)