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

What to put in the message

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

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)