# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill github-webhooks` ([details](https://hookdeck.com/webhooks/github/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [GitHub's official docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads).

[Overview](https://hookdeck.com/webhooks/github) · [Webhook events (76)](https://hookdeck.com/webhooks/github/events) · [MCP events](https://hookdeck.com/webhooks/github/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/github/verify) · [Production guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/github/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Hub-Signature-256` Format: sha256=<hex> | [GitHub docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| Scheme | `HMAC-SHA256` | [GitHub docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| Signed material | `{raw body}` The request body as sent, with no timestamp or other data added. | [GitHub docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| How events are identified | `x-github-event header and action field in the body` | [GitHub docs](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks) |
| Body format | `JSON` Content type: application/json, application/x-www-form-urlencoded. | [GitHub docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| Legacy signature | `X-Hub-Signature` HMAC-SHA1 hex digest of the raw body with the same secret, sent only for compatibility with existing integrations. | [GitHub docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| Other headers | `x-github-delivery, x-github-event, x-github-hook-id, x-github-hook-installation-target-id, x-github-hook-installation-target-type` | [Registry record](https://hookdeck.com/webhooks/github.json) |
| Envelope | `action, enterprise, installation, organization, repository, sender` | [GitHub docs](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill github-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/github/skill) |

[Verify GitHub webhooks](https://hookdeck.com/webhooks/github/verify)

## 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.

## 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 `ping` event once a webhook is created.
- Test locally with the GitHub CLI: run `gh extension install cli/gh-webhook`, then `gh 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

- **Timeout:** 10 seconds. GitHub then closes the connection and records a failure. [Guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** none. GitHub doesn't redeliver failed deliveries automatically. [Guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#retries)
- **After a failure:** 3 days to redeliver. by hand or through the REST API, from the deliveries log. [Guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#retries)
- **Ordering:** not guaranteed. compare the timestamps in the payload. [Guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#ordering)

## Known failure modes

1. **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](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#retries)
2. **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](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#timeouts)
3. **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](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#ordering)
4. **Redeliveries repeat the event.** A redelivery has the same `X-GitHub-Delivery` value as the original. Record each value you process and skip repeats. [Handle duplicates](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#duplicates)

From [Hookdeck's GitHub guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts).

## GitHub webhook best practices

- **[Set a secret and verify every signature](https://hookdeck.com/webhooks/github/verify).** Without a secret GitHub sends no signature, and anyone who finds your URL can send fake events to it.
- **[Respond within 10 seconds](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#retries).** Run a scheduled job that finds failed deliveries and redelivers them through the REST API within the 3-day window.
- **[Track X-GitHub-Delivery](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#choosing-events).** GitHub keeps adding event types and actions, so branch on both and ignore anything you don't recognise.
- **[Subscribe only to events you process](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts#choosing-events).** 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](https://hookdeck.com/webhooks/github/events#push): Commits or tags pushed, or a branch or tag deleted
- [create](https://hookdeck.com/webhooks/github/events#create): Git branch or tag created
- [delete](https://hookdeck.com/webhooks/github/events#delete): Git branch or tag deleted
- [release](https://hookdeck.com/webhooks/github/events#release): Release created, published, edited or deleted

### Pull requests and issues

- [pull_request](https://hookdeck.com/webhooks/github/events#pull_request): Pull request opened, closed, edited, labeled or otherwise changed
- [pull_request_review](https://hookdeck.com/webhooks/github/events#pull_request_review): Pull request review submitted, edited or dismissed
- [issues](https://hookdeck.com/webhooks/github/events#issues): Issue opened, edited, closed, labeled or otherwise changed
- [issue_comment](https://hookdeck.com/webhooks/github/events#issue_comment): Comment on an issue or pull request created, edited or deleted

### CI and deployments

- [workflow_run](https://hookdeck.com/webhooks/github/events#workflow_run): Actions workflow run requested, in progress or completed
- [workflow_job](https://hookdeck.com/webhooks/github/events#workflow_job): Actions workflow job queued, waiting, running or finished
- [check_run](https://hookdeck.com/webhooks/github/events#check_run): Check run created, completed or re-requested
- [deployment_status](https://hookdeck.com/webhooks/github/events#deployment_status): A deployment's status changes

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [repository](https://hookdeck.com/webhooks/github/events#resource-repository) | 14 | 12 |
| [organization](https://hookdeck.com/webhooks/github/events#resource-organization) | 9 | 7 |
| [security](https://hookdeck.com/webhooks/github/events#resource-security) | 9 | 6 |
| [code](https://hookdeck.com/webhooks/github/events#resource-code) | 8 | 8 |
| [issues](https://hookdeck.com/webhooks/github/events#resource-issues) | 7 | 4 |
| [installation](https://hookdeck.com/webhooks/github/events#resource-installation) | 6 | 4 |
| [project](https://hookdeck.com/webhooks/github/events#resource-project) | 6 | 4 |
| [deployment](https://hookdeck.com/webhooks/github/events#resource-deployment) | 5 | 4 |
| [checks](https://hookdeck.com/webhooks/github/events#resource-checks) | 4 | 4 |
| [pull_request](https://hookdeck.com/webhooks/github/events#resource-pull-request) | 4 | 4 |

1 more resource. [All 76 events](https://hookdeck.com/webhooks/github/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/github/events): Every covered GitHub event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/github/mcp-events): How an agent subscribes to GitHub events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/github/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/github/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/github/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill github-webhooks`
---

Not affiliated with GitHub. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/github.json) · [Report a correction](https://hookdeck.com/contact)
