Debug a GitHub Webhook That Isn't Reaching Your Server

What Recent Deliveries Is Telling You

Six Checks, in Order

1. 01

   Open the delivery log in GitHub

   Go to the repository's Settings → Webhooks, edit the webhook and open Recent Deliveries. Each delivery shows the request GitHub sent and the response it got back. If a newly triggered event is not listed, check the selected events, the Active checkbox and that you are looking at the right webhook (repository, organization or GitHub App).

2. 02

   Read what the failed delivery says

   A connection error or timeout with no HTTP status means GitHub could not reach the Payload URL or your server took longer than 10 seconds to answer. A 2xx status means the delivery succeeded. A 4xx or 5xx status means something answered with an error: your app, or a reverse proxy, load balancer or tunnel in front of it.

3. 03

   Fix 4xx and 5xx responses

   404 usually means the Payload URL path does not match your route, 405 means the route does not accept POST, and 401 or 403 usually come from signature checks, auth or CSRF middleware. A 500 usually comes from your app, but 502, 503 and 504 are often returned by a proxy or load balancer that could not reach your app or got no answer from it, so check the proxy's upstream and that the app is running before reading handler logs. The Response tab in Recent Deliveries shows the body and headers that came back.

4. 04

   Check the X-Hub-Signature-256 signature

   Compute an HMAC-SHA256 of the raw request body with the webhook secret, prefix it with sha256= and compare it to the header in constant time. Most mismatches come from hashing re-serialized JSON instead of the raw bytes, or from a secret that differs from the one saved in GitHub.

5. 05

   Check the tunnel when testing on localhost

   GitHub cannot reach localhost. Run hooklistener tunnel --port 3000, use the printed HTTPS URL plus your route as the Payload URL, and watch the tunnel log. If GitHub reports a failure but the tunnel log is empty, check the URL and tunnel connection; if the tunnel shows the request but your app logs nothing, check the app is listening on the configured host and port (for an app in Docker, publish the container port and tunnel to that host port).

6. 06

   Redeliver and confirm a 2xx

   GitHub does not retry failed deliveries on its own. While you iterate, you can replay the captured request from Hooklistener and check each attempt's status in Hooklistener and your app logs; these replays do not go through GitHub and do not change Recent Deliveries. Once the handler works, click Redeliver on the failed delivery in GitHub and confirm the new attempt shows a 2xx in Recent Deliveries.

No Delivery at All

Check a newly triggered event: GitHub only lists deliveries from the past three days. Confirm that the webhook is Active and subscribes to that event; selecting only push will not send pull_request or issues events. Repository, organization and GitHub App webhooks have separate logs (App deliveries are in its settings, under Advanced). GitHub also skips payloads larger than 25 MB.

Creating a webhook sends a ping event. If it failed, inspect its response before triggering another event. If it is missing, confirm you opened the correct webhook.

Connection Errors and Timeouts

Trace 4xx and 5xx to the Component That Returned Them

Open the failed delivery's Response tab for its status, headers and body. A proxy error page can explain why your handler logged nothing. Compare the Request tab's X-GitHub-Delivery with your app logs and use the status table above. For 401/403, check session auth and CSRF middleware as well as the signature; exempt only the webhook route from browser-session checks and keep signature verification.

A 413 means a server or proxy body-size limit rejected the payload. A 500 can come from reading a pull_request field on a ping event: route on X-GitHub-Event before accessing event-specific fields. For 502/503/504, verify the app is running and the proxy's upstream host and port match it. A 2xx only confirms HTTP acceptance; check worker logs separately if the expected action never happens.

X-Hub-Signature-256 Mismatches

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.GITHUB_WEBHOOK_SECRET;
if (!secret) throw new Error("Set GITHUB_WEBHOOK_SECRET before starting");

// Raw body for this route only, so the bytes match what GitHub signed.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!Buffer.isBuffer(req.body)) return res.sendStatus(415);
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(req.body)
      .digest("hex");
  const received = req.get("X-Hub-Signature-256") ?? "";

  const receivedBytes = Buffer.from(received, "utf8");
  const expectedBytes = Buffer.from(expected, "utf8");
  const valid =
    receivedBytes.length === expectedBytes.length &&
    crypto.timingSafeEqual(receivedBytes, expectedBytes);
  if (!valid) return res.status(401).send("bad signature");

  const event = req.get("X-GitHub-Event");
  const payload = JSON.parse(req.body.toString("utf8"));
  // enqueue work for event/payload here
  res.status(202).send("ok");
});

app.listen(3000);

Tunnel Checks for Localhost

npm install -g hooklistener
hooklistener login
hooklistener tunnel --port 3000
# Forwarding: https://abc123.hook.events → http://localhost:3000

Isolate GitHub From Your Server

hooklistener listen --endpoint ep_abc123 --port 3000 --path-prefix /webhook

Frequently Asked Questions