GitHub webhooks

How to Test GitHub Webhooks (and Verify X-Hub-Signature-256)

GitHub sends a webhook when something happens in a repository, organisation or app: a push, a pull request, a release. Here is how to see those deliveries and trust them.

Capture a real GitHub webhook in a minute

  1. Get a URL. Use the button on this page. It opens the inspector with a fresh URL that is ready to receive.
  2. Give it to GitHub. In the repository or organisation, open Settings → Webhooks → Add webhook. Paste the URL as the payload URL, choose application/json as the content type and set a secret.
  3. Trigger an event. The request appears in the inspector as it arrives, with GitHub recognised and the event name shown.
  4. Check the signature. Open Verify signature, paste your secret and confirm the request is genuine. The check runs in your browser.

Headers GitHub sends

HeaderMeaning
X-GitHub-EventThe event name, such as push, pull_request or ping.
X-GitHub-DeliveryA unique ID for this delivery. Use it to detect duplicates.
X-Hub-Signature-256sha256= followed by the HMAC-SHA256 of the body, in hex. Present only when you set a secret.
X-Hub-SignatureThe older SHA-1 variant. Prefer the SHA-256 header.
X-GitHub-Hook-IDThe ID of the webhook configuration that fired.
User-AgentBegins with GitHub-Hookshot/.

When you create a webhook, GitHub immediately sends a ping event. It is the quickest way to confirm the URL is reachable, and it will be the first request in your inspector.

Verifying the signature

GitHub computes an HMAC-SHA256 over the raw request body with the secret you configured and sends it as sha256=<hex>.

Verifying X-Hub-Signature-256 (Node.js)
import crypto from "node:crypto";

export function verifyGitHub(rawBody, header, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = header ?? "";
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}
Compare in constant timeA plain === leaks how many leading characters matched through timing. Use crypto.timingSafeEqual, or the equivalent in your language, for any signature comparison.

What GitHub expects back

  • A 2xx response within 10 seconds. Slower responses are recorded as failed. Queue the work and answer immediately.
  • No automatic retries. GitHub does not redeliver a failed delivery on its own. You can redeliver from the webhook's Recent Deliveries tab or through the REST API.
  • Large payloads are capped. GitHub does not deliver payloads over 25 MB.

A productive debugging loop

Because redelivery is manual, GitHub is pleasant to iterate against: push once, then press Redeliver as often as you like while you change your handler. Combine that with forwarding from webhook.stream to localhost and you never need to make another commit just to trigger an event.

Frequently asked questions

What is the difference between X-Hub-Signature and X-Hub-Signature-256?

They sign the same body with the same secret, using SHA-1 and SHA-256 respectively. GitHub sends both for compatibility. New code should verify X-Hub-Signature-256.

Does GitHub retry failed webhook deliveries?

No. Failed deliveries are not retried automatically. Redeliver them from the Recent Deliveries list or with the REST API.

Should I choose JSON or form encoding?

Choose application/json. With form encoding the JSON arrives URL-encoded inside a payload parameter, which is harder to work with and easy to verify incorrectly.