GitHub webhook not triggering? Diagnose it in 5 minutes

Your webhook is configured, you push a commit, and… nothing happens. The failure is in one of exactly three places: GitHub never attempted a delivery, GitHub attempted it and it failed, or it was delivered but your code did nothing visible. The fix is different for each, so the first job is figuring out which one you have.

1. Check Recent Deliveries first

Repo → Settings → Webhooks → your hook → Recent Deliveries. This log answers the first question instantly:

• No entry for your event → GitHub never attempted a delivery. Go to §2.
• Entry with a red ✗ → delivery was attempted and failed. The response tab shows GitHub's error (timed out, failed to connect to host, certificate errors, or your own 4xx/5xx). Go to §3.
• Entry with a green ✓ → GitHub delivered fine; the bug is in your handler. Go to §4.

Two timing gotchas before you conclude anything: deliveries can take a few minutes to happen and to appear in the log, and deliveries may arrive out of order — use the timestamps in the payload, not arrival order.

2. GitHub never attempted a delivery

All of these are documented, and all of them look like "webhook is broken":

• Not subscribed to the event. The default is just the push event. Opening an issue, a PR, a release — none of those fire unless you selected them under "Let me select individual events". This is the #1 cause.
• Event triggered in the wrong place. A repository webhook only fires for events in that repository; org webhooks are configured separately.
• The hook is inactive. The "Active" checkbox can be off — or GitHub auto-disabled the hook (an OAuth-app-created webhook in an org with OAuth access restrictions gets disabled automatically).
• Documented event limits. Push more than 3 tags at once and the push event is not triggered for that push. Payloads are capped at 25 MB — a bigger event (e.g. a create with many branches) is silently not delivered.
• localhost URL. GitHub can't reach http://localhost:3000 — it's rejected outright ("URL host localhost is not supported"). See §5 for the fix.
• Still nothing? Check githubstatus.com.

3. Delivery attempted but failing

The Recent Deliveries response tab tells you which one:

• timed out — your server must respond 2xx within 10 seconds or GitHub terminates the connection and records a failure. Respond first, process after (queue the work).
• Certificate errors — self-signed cert, or your server isn't sending the full certificate chain. Test your endpoint with SSL Labs' server test.
• failed to connect to host / network — DNS, firewall, or your server refusing the connection. If you allow-list IPs, GitHub's hook ranges come from the /meta REST endpoint and change over time.
• invalid HTTP response — your endpoint returned 4xx/5xx. Only 2xx counts as success.

Isolate infrastructure from code: point the webhook at a capture URL (button below, or curl https://hookden.pages.dev/new) and hit Redeliver in Recent Deliveries. If the delivery lands in the bin with a green 2xx, GitHub and the event are fine — the problem is your server's TLS, network, or response. If it doesn't land, the problem is on the GitHub side of the fence (§2).

4. Delivered fine, but your handler misbehaves

Send one real delivery into a bin and look at what your code actually has to parse: the X-GitHub-Event header (your router may be ignoring ping — the very first delivery every new webhook receives is a ping, not a real event), the X-GitHub-Delivery GUID (log it — it matches the Recent Deliveries entry), and the exact JSON body. Then replay that capture against your real endpoint as many times as you need — no more pushing empty commits to retrigger events. If you verify X-Hub-Signature-256, the bin shows a ✓/✗ badge when you paste your secret: verifying GitHub signatures.

5. Developing on localhost

GitHub rejects localhost URLs, so give it a capture URL instead and pull deliveries down to your machine:

$ curl https://hookden.pages.dev/cli > hookden && chmod +x hookden
$ ./hookden relay YOUR_BIN http://localhost:3000/webhook

Bodies are re-delivered byte-identical, so X-Hub-Signature-256 still verifies locally. No tunnel, no ngrok, nothing exposed to the internet — details at /relay.

← All guides · Docs · Hookden vs webhook.site