GitHub webhooks
GitHub webhooks are HTTP POST requests that tell your server when events you subscribe to happen in a repository, organization, GitHub App, Marketplace listing or Sponsors account.
How GitHub webhooks work
Webhooks push events to your server as they happen, so you don't have to poll the REST API and spend your rate limit. When a subscribed event occurs, GitHub sends an HTTP POST to your URL. The body is JSON, or a form field called payload that holds the same JSON if you pick the form content type.
The X-GitHub-Event header names the event, and the top-level action field in the body says what happened, so an issues delivery might be opened or closed. Some events, such as push, have no action. X-GitHub-Delivery identifies the delivery. GitHub's webhook docs name no version header or field for payloads.
Key facts
{raw body} The request body as sent, with no timestamp or other data added.
X-Hub-Signature HMAC-SHA1 hex digest of the raw body with the same secret, sent only for compatibility with existing integrations.
x-github-delivery, x-github-event, x-github-hook-id, x-github-hook-installation-target-id, x-github-hook-installation-target-type Setting up GitHub webhooks
- Create a webhook under Webhooks in a repository's or organization's settings, or with the REST API, then choose its URL, content type, secret and events. GitHub Apps, Marketplace listings and Sponsors accounts have their own webhook settings. GitHub sends a
pingevent once a webhook is created. - Test locally with the GitHub CLI: run
gh extension install cli/gh-webhook, thengh webhook forward --repo=REPOSITORY --events=EVENTS --url=URL. It works for repository and organization webhooks. For other types, use a proxy URL from smee.io. - Redeliver a delivery from the past 3 days from the webhook's Recent deliveries list, or with the REST API.
Delivery behaviour
Known failure modes
From Hookdeck's GitHub guide →-
Failed deliveries aren't retried
GitHub doesn't retry a failed delivery. Redeliver it yourself within 3 days, by hand or through the REST API.
Retries and redelivery → -
Slow handlers lose events
GitHub closes the connection after 10 seconds, records a failure and doesn't retry. Return a 2xx straight away and process the event from a queue.
Handle timeouts → -
Out-of-order delivery
GitHub may deliver webhooks in a different order from the events that caused them. Compare the timestamps in the payload when order matters.
Handle ordering → -
Redeliveries repeat the event
A redelivery has the same
Handle duplicates →X-GitHub-Deliveryvalue as the original. Record each value you process and skip repeats.
GitHub webhook best practices
- Set a secret and verify every signature. Without a secret GitHub sends no signature, and anyone who finds your URL can send fake events to it.
- Respond within 10 seconds. Return a 2xx and process the event from a queue. GitHub treats a slower response as a failure and won't retry it.
- Redeliver what you missed. Run a scheduled job that finds failed deliveries and redelivers them through the REST API within the 3-day window.
- Track X-GitHub-Delivery. A redelivery has the same value as the original, so a record of processed IDs stops you handling it twice.
- Check the event and the action. GitHub keeps adding event types and actions, so branch on both and ignore anything you don't recognise.
- Subscribe only to events you process. Every extra event is work for your server, and fewer deliveries lower your chance of being throttled during a surge.
Common GitHub webhook events
Code
push | Commits or tags pushed, or a branch or tag deleted |
create | Git branch or tag created |
delete | Git branch or tag deleted |
release | Release created, published, edited or deleted |
Pull requests and issues
pull_request | Pull request opened, closed, edited, labeled or otherwise changed |
pull_request_review | Pull request review submitted, edited or dismissed |
issues | Issue opened, edited, closed, labeled or otherwise changed |
issue_comment | Comment on an issue or pull request created, edited or deleted |
CI and deployments
workflow_run | Actions workflow run requested, in progress or completed |
workflow_job | Actions workflow job queued, waiting, running or finished |
check_run | Check run created, completed or re-requested |
deployment_status | A deployment's status changes |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
repository | 14 | 12 |
organization | 9 | 7 |
security | 9 | 6 |
code | 8 | 8 |
issues | 7 | 4 |
installation | 6 | 4 |
project | 6 | 4 |
deployment | 5 | 4 |
checks | 4 | 4 |
pull_request | 4 | 4 |
1 more resource. All 76 events →
In this hub
| Webhook events → | Every covered GitHub event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to GitHub events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill github-webhooks |
Stop losing GitHub events when your endpoint is down.
GitHub won't retry a failed delivery. Hookdeck Event Gateway accepts every GitHub delivery, verifies the signature, queues events and retries to your service on your schedule.