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.

76 events covered 10 captured samples

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

Signature header
X-Hub-Signature-256

Format: sha256=<hex>

Scheme
HMAC-SHA256
Signed material
{raw body}

The request body as sent, with no timestamp or other data added.

How events are identified
x-github-event header and action field in the body
Body format
JSON

Content type: application/json, application/x-www-form-urlencoded.

Legacy signature
X-Hub-Signature

HMAC-SHA1 hex digest of the raw body with the same secret, sent only for compatibility with existing integrations.

Other headers
x-github-delivery, x-github-event, x-github-hook-id, x-github-hook-installation-target-id, x-github-hook-installation-target-type
Envelope
action, enterprise, installation, organization, repository, sender
Agent skill
npx skills add hookdeck/webhook-skills --skill github-webhooks

Verify GitHub webhooks →

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

  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 →
  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 →
  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 →
  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 →

GitHub webhook best practices

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

star · ping · branch_protection_configuration · branch_protection_rule +10

14 12
organization

custom_property · custom_property_values · member · membership +5

9 7
security

code_scanning_alert · dependabot_alert · repository_advisory · repository_vulnerability_alert +5

9 6
code

push · release · create · delete +4

8 8
issues

issues · issue_comment · issue_dependencies · issue_relates_to +3

7 4
installation

github_app_authorization · · _repositories · _target +2

6 4
project

project · _card · _column · s_v2 +2

6 4
deployment

deployment · deploy_key · _protection_rule · _review +1

5 4
checks

check_run · check_suite · merge_group · status

4 4
pull_request

pull_request · _review · _review_comment · _review_thread

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.

Not affiliated with GitHub. Facts are compiled from public sources and linked inline.