GitHub webhooks

Capture GitHub webhook deliveries and verify X-Hub-Signature-256 before you write the handler.

Get a test URL

Point GitHub at this URL

1. Create a test endpoint below and copy its URL.
2. In your repository, open Settings → Webhooks → Add webhook.
3. Paste the Webhook Studio URL as the Payload URL and set Content type to application/json.
4. Set a secret so GitHub signs deliveries, then choose the events to send.
5. Save. GitHub immediately sends a ping event — you should see it in the Inbox.

What a GitHub delivery looks like

A representative body, using GitHub’s field names. Your own deliveries appear in the Inbox exactly as sent, headers and raw bytes included.

{
  "ref": "refs/heads/main",
  "before": "9f2c1d4e8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
  "after": "3a7b81c2f5e6d7c8b9a0f1e2d3c4b5a6978869a0",
  "created": false,
  "deleted": false,
  "forced": false,
  "repository": {
    "id": 812345678,
    "node_id": "R_kgDOMHq1Ng",
    "name": "checkout-service",
    "full_name": "acme/checkout-service",
    "private": true,
    "default_branch": "main"
  },
  "pusher": {
    "name": "octocat",
    "email": "octocat@users.noreply.github.com"
  },
  "sender": {
    "login": "octocat",
    "id": 583231,
    "type": "User"
  },
  "commits": [
    {
      "id": "3a7b81c2f5e6d7c8b9a0f1e2d3c4b5a6978869a0",
      "message": "Verify the signature before parsing the body",
      "timestamp": "2026-07-21T09:14:02+08:00",
      "author": {
        "name": "Octocat",
        "username": "octocat"
      },
      "added": [],
      "removed": [],
      "modified": [
        "server/webhooks.js"
      ]
    }
  ],
  "head_commit": {
    "id": "3a7b81c2f5e6d7c8b9a0f1e2d3c4b5a6978869a0",
    "message": "Verify the signature before parsing the body",
    "timestamp": "2026-07-21T09:14:02+08:00"
  }
}

Delivery headers

Event types

The events worth handling first. See GitHub’s own documentation for the complete list.

Verify the X-Hub-Signature-256 header

GitHub signs each delivery with HMAC-SHA256 over the raw request body, keyed on your webhook secret. Verify before you parse, and before you act.

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Raw body again: the digest is over the exact bytes GitHub sent.
app.post('/webhooks/github', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.GITHUB_WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

  // timingSafeEqual, never ===. A plain comparison returns early on the first
  // wrong byte, which leaks the correct signature one byte at a time. It also
  // throws on a length mismatch, so check length first.
  const valid =
    typeof signature === 'string' &&
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!valid) return res.status(401).send('Invalid signature');

  res.status(202).send('accepted');

  const event = req.headers['x-github-event'];
  const delivery = req.headers['x-github-delivery']; // dedupe key
  const payload = JSON.parse(req.body.toString('utf8'));

  if (event === 'push') {
    // handle(payload) — idempotently, keyed on `delivery`
  }
});

Retries and delivery guarantees

GitHub does not retry failed deliveries automatically the way payment providers do. Failures sit in the repository's Recent Deliveries tab, where each one can be redelivered by hand or through the REST API. That makes the delivery log your safety net: if your handler was down for an hour, nothing re-arrives on its own. Payloads are capped at 25 MB and larger ones are not delivered at all.

Common pitfalls

FAQ