GitHub webhook testing: deliveries, signatures and redelivery
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:
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
| Header | Meaning | Use it for |
|---|---|---|
X-GitHub-Event | The event that triggered the delivery (push, pull_request, ping…) | Routing; then check the payload's action field |
X-GitHub-Delivery | A GUID for the delivery; unchanged when it's redelivered | Deduplication and replay protection |
X-Hub-Signature-256 | sha256= + hex HMAC-SHA256 of the body (only if a secret is set) | Authenticating the request |
X-GitHub-Hook-ID | The webhook's ID | Telling several webhooks apart |
X-GitHub-Hook-Installation-Target-Type | Where the webhook was created (repository, organization, app…) | Multi-tenant routing |
X-GitHub-Hook-Installation-Target-ID | The ID of that resource | Multi-tenant routing |
User-Agent | Always 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
| Method | How | Notes |
|---|---|---|
| Ping | Created automatically with the webhook; also via the REST API for repository and organization webhooks | Checks URL, TLS and signature, with no side effects |
| Test push | REST API, for repository webhooks subscribed to push | A realistic push payload without pushing |
| Redeliver | Settings → 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 HookWatcher | Use a HookWatcher URL as the payload URL, then deliver or replay to localhost | No 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:
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();
});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 raisesBoth 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 endpointTroubleshooting
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:
| Message or symptom | Cause | Fix |
|---|---|---|
| "URL host localhost is not supported" | Payload URL points at your machine | Use a public URL that forwards to localhost |
| "Failed to connect to host" | The URL doesn't resolve, or a network restriction blocks GitHub | Check DNS and firewall rules; GitHub's IP ranges are in the /meta API |
| "Failed to connect to network" | Your server refused the connection | Check the server is listening on that port and host |
| "Timed out" | No response within 10 seconds | Respond 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 chain | Serve the full chain from a trusted CA; keep SSL verification on |
| "Invalid HTTP response" | Your server answered 4xx or 5xx | Find the error in your logs; replay the captured delivery against your code |
| Signature never matches | No secret configured (no header is sent), wrong secret, wrong header or algorithm, or the body was changed before verification | Set the secret; use X-Hub-Signature-256 with SHA-256 over the raw body; for form deliveries sign the form body |
| No deliveries listed | Event not subscribed, webhook inactive, event in another repository or organization, or a documented limit | Check 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 organization | Fan out from one endpoint, for example with forwarding to several destinations |
| A failed delivery never comes back | GitHub doesn't retry automatically | Redeliver within 3 days, or replay the captured copy |
| Events in an unexpected order | GitHub may deliver in a different order | Use timestamps in the payload, not arrival order |
Test your GitHub webhook events
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 Docs: Webhook events and payloads (headers, ping, push, payload cap)
- GitHub Docs: Validating webhook deliveries
- GitHub Docs: Best practices for using webhooks
- GitHub Docs: Creating webhooks (content types)
- GitHub Docs: Testing webhooks
- GitHub Docs: Redelivering webhooks
- GitHub Docs: Troubleshooting webhooks
GitHub's IP ranges: REST API /meta.