Debug GitHub webhooks locally

Guides / Providers

GitHub signs each delivery with X-Hub-Signature-256: sha256=<hex HMAC-SHA256>, computed over the raw body with your webhook secret. There is no timestamp, so an exact replay of a captured GitHub delivery still carries a valid signature. The event name is in X-GitHub-Event and each delivery has a GUID in X-GitHub-Delivery. (Every header, both content types and delivery errors: GitHub webhook testing.)

Receive GitHub webhooks on localhost

hwcli listen repo-events --forward :3000/webhooks/github --include-sensitive

Add the endpoint URL under the repository's or organization's Settings → Webhooks, with content type application/json. GitHub sends a ping event when the webhook is created, so the first request arrives immediately. --include-sensitive delivers the signature header, so your handler verifies it exactly as in production. HookWatcher labels each request with its event, such as push or pull_request.

Verify and re-sign

Save the webhook secret in Endpoint settings → Signature. On paid plans HookWatcher checks every captured delivery against the exact bytes it received and shows whether the signature matched. The secret is stored encrypted and never shown again. Modified replays can carry a new valid signature:

hwcli replay evt_4e1a90c2                                  # exact, signature still valid
hwcli replay evt_4e1a90c2 --set action=closed --resign      # changed body, new valid signature
hwcli replay evt_4e1a90c2 --invalid-signature               # your handler should reject this

Things to test for GitHub

  • Response time: GitHub treats a delivery as failed if your server doesn't respond within 10 seconds. Queue slow work and answer first; every replay records how long your handler took.
  • No automatic retries: GitHub doesn't redeliver failed deliveries on its own. A delivery your code dropped is gone unless someone redelivers it by hand, or you replay the captured copy.
  • Event filtering: one webhook can send many event types. Replay a ping and an event you don't handle, and check both get a 2xx without side effects.
  • Raw bodies: verify the signature over the bytes received, before parsing JSON. Exact replays show at once whether your framework changes the body first.

Create an endpoint and capture your first webhook. No signup needed.

Start Free