GitHub webhook testing: deliveries, signatures and redelivery

GitHub signs every delivery, gives each one a unique ID, waits 10 seconds for your answer, and doesn't retry when you fail. Those four facts decide how to test a GitHub webhook handler: verify signatures over the raw body, deduplicate on the delivery ID, answer fast, and have a way to get failed deliveries back.
Get a free webhook URL Free, no account needed.

By the HookWatcher team · Updated

What a GitHub delivery looks like

When you create a webhook, GitHub immediately sends a ping event to confirm the configuration. This is a ping in GitHub's format (values are examples), signed with GitHub's documented test secret:

A ping delivery (content type application/json)
POST /webhooks/github HTTP/1.1
Host: example.com
User-Agent: GitHub-Hookshot/044aadd
Content-Type: application/json
X-GitHub-Event: ping
X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
X-GitHub-Hook-ID: 292430182
X-GitHub-Hook-Installation-Target-Type: repository
X-GitHub-Hook-Installation-Target-ID: 1296269
X-Hub-Signature-256: sha256=144757a66ba50a12daf5768f6f8f028b1cf0e57aceca5339a320fdccd93455f3

{"zen":"Design for failure.","hook_id":292430182,"hook":{"type":"Repository","id":292430182,"name":"web","active":true,"events":["push","pull_request"],"config":{"content_type":"json","insecure_ssl":"0","url":"https://hookwatcher.com/<endpoint-id>"}},"repository":{"id":1296269,"full_name":"octocat/Hello-World"},"sender":{"login":"octocat","id":1}}

The signature is HMAC-SHA256 of exactly that body with the secret It's a Secret to Everybody; check it in the signature generator. GitHub also sends the legacy SHA-1 X-Hub-Signature when a secret is set; use the SHA-256 one.

JSON or form?

The webhook's content type setting decides the body. application/json sends the JSON as the body. application/x-www-form-urlencoded sends it as a form parameter named payload, and the signature then covers the form body, not the JSON inside it. For the ping above, that body starts payload=%7B%22zen%22%3A%22Design+for+failure. and its signature is sha256=0c95f348945c1fe4…. GitHub recommends JSON when you have the choice.

Delivery headers

GitHub webhook delivery headers
HeaderMeaningUse it for
X-GitHub-EventThe event that triggered the delivery (push, pull_request, ping…)Routing; then check the payload's action field
X-GitHub-DeliveryA GUID for the delivery; unchanged when it's redeliveredDeduplication and replay protection
X-Hub-Signature-256sha256= + hex HMAC-SHA256 of the body (only if a secret is set)Authenticating the request
X-GitHub-Hook-IDThe webhook's IDTelling several webhooks apart
X-GitHub-Hook-Installation-Target-TypeWhere the webhook was created (repository, organization, app…)Multi-tenant routing
X-GitHub-Hook-Installation-Target-IDThe ID of that resourceMulti-tenant routing
User-AgentAlways starts with GitHub-Hookshot/Logging only; anyone can send it

Payloads are capped at 25 MB: GitHub doesn't deliver larger ones (for example a create event when many branches or tags are pushed at once). A push payload lists at most 2,048 commits.

Ways to send test deliveries

Sending GitHub test deliveries
MethodHowNotes
PingCreated automatically with the webhook; also via the REST API for repository and organization webhooksChecks URL, TLS and signature, with no side effects
Test pushREST API, for repository webhooks subscribed to pushA realistic push payload without pushing
RedeliverSettings → Webhooks → the webhook → Recent deliveries → the delivery → Redeliver (or the REST API)Deliveries from the past 3 days; repository admins or organization owners. Same X-GitHub-Delivery
Capture with HookWatcherUse a HookWatcher URL as the payload URL, then deliver or replay to localhostNo timestamp in GitHub's signature, so exact replays stay valid; captures are kept for your plan's retention, independent of GitHub's 3-day redelivery window

Verify X-Hub-Signature-256

Compute the HMAC over the raw body before parsing, compare in constant time (GitHub says never to use ==), and only then parse JSON or the form's payload:

Node.js (Express), JSON and form deliveries
const crypto = require("node:crypto");
const express = require("express");

const app = express();

app.post("/webhooks/github", express.raw({ type: "*/*" }), (req, res) => {
  const header = req.get("X-Hub-Signature-256") || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.GITHUB_WEBHOOK_SECRET)
    .update(req.body) // raw bytes: JSON or the form body, exactly as sent
    .digest("hex");
  const received = Buffer.from(header);
  const wanted = Buffer.from(expected);
  // Compare byte lengths first: timingSafeEqual throws when they differ.
  if (received.length !== wanted.length || !crypto.timingSafeEqual(received, wanted)) {
    return res.status(401).send("invalid signature");
  }

  const delivery = req.get("X-GitHub-Delivery"); // same value on redelivery
  const event = req.get("X-GitHub-Event");
  const text = req.body.toString("utf8");
  const payload = req.is("application/x-www-form-urlencoded")
    ? JSON.parse(new URLSearchParams(text).get("payload"))
    : JSON.parse(text);

  if (event === "ping") return res.status(204).end();
  enqueue(delivery, event, payload); // skip deliveries you've already processed
  res.status(202).end();
});
Python, standard library only
import hashlib
import hmac


def verify_github(payload: bytes, header: str, secret: str) -> bool:
    """X-Hub-Signature-256 check: sha256=<hex HMAC-SHA256 of the raw body>."""
    if not header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), header.encode())  # bytes: never raises

Both are tested against the example deliveries on this page and GitHub's published test vector (secret It's a Secret to Everybody, body Hello, World!, signature sha256=757107ea…3e17).

Try it live

Try it: verify GitHub deliveries

Live, on a real endpoint
Three GitHub-format deliveries to a real endpoint, covering both content types and a redelivery.
No account. The endpoint is yours in this browser and also opens in the playground.

Troubleshooting

Start in the webhook's Recent deliveries list: each delivery shows the request GitHub sent and the response it got. The messages there map to these causes:

GitHub webhook delivery errors
Message or symptomCauseFix
"URL host localhost is not supported"Payload URL points at your machineUse a public URL that forwards to localhost
"Failed to connect to host"The URL doesn't resolve, or a network restriction blocks GitHubCheck DNS and firewall rules; GitHub's IP ranges are in the /meta API
"Failed to connect to network"Your server refused the connectionCheck the server is listening on that port and host
"Timed out"No response within 10 secondsRespond with a 2xx right away and process in a background job
"Peer certificate cannot be authenticated with given CA certificates"Self-signed certificate or incomplete chainServe the full chain from a trusted CA; keep SSL verification on
"Invalid HTTP response"Your server answered 4xx or 5xxFind the error in your logs; replay the captured delivery against your code
Signature never matchesNo secret configured (no header is sent), wrong secret, wrong header or algorithm, or the body was changed before verificationSet the secret; use X-Hub-Signature-256 with SHA-256 over the raw body; for form deliveries sign the form body
No deliveries listedEvent not subscribed, webhook inactive, event in another repository or organization, or a documented limitCheck the webhook's events and Active box; wait a few minutes
"Cannot have more than 20 webhooks"20 webhooks per event type per repository or organizationFan out from one endpoint, for example with forwarding to several destinations
A failed delivery never comes backGitHub doesn't retry automaticallyRedeliver within 3 days, or replay the captured copy
Events in an unexpected orderGitHub may deliver in a different orderUse timestamps in the payload, not arrival order

Test your GitHub webhook events

Use a free HookWatcher URL as your webhook's payload URL. The ping arrives immediately, labelled as GitHub with its event, with every header and the exact body.
Get a free webhook URL No account or card needed. Want to keep it? Create a free account

Frequently asked questions

Does GitHub retry failed webhook deliveries?

No. GitHub doesn't redeliver failed deliveries automatically. Redeliver from Recent deliveries or the REST API within 3 days, or keep a captured copy you can replay later.

How do I test a GitHub webhook locally?

GitHub won't send to localhost. Give it a public URL that relays to your machine: a forwarding service, a tunnel, or a HookWatcher endpoint with hwcli listen, which also keeps each delivery for replay.

Why is my redelivered event processed twice?

A redelivery has the same X-GitHub-Delivery as the original. Record processed delivery IDs and skip ones you've seen, answering 2xx so GitHub records success.

Does HookWatcher verify GitHub signatures?

On paid plans, yes: save the webhook secret and every capture is checked against the exact bytes received. Replays can be re-signed after you change the body.

Should I use X-Hub-Signature or X-Hub-Signature-256?

X-Hub-Signature-256. X-Hub-Signature uses SHA-1 and exists for compatibility.

Sources

GitHub's IP ranges: REST API /meta.