Webhook providers need a public HTTPS URL. Your code runs on localhost:3000. There are three common ways to connect the two, and each one can break signature checks in its own way.
1. The provider's own CLI
Stripe ships one:
stripe listen --forward-to localhost:3000/webhooks/stripe
It prints a signing secret (whsec_...) that is different from the one in your dashboard. Use that one locally, or every event fails verification. It only works for Stripe, and most providers have nothing like it.
2. A tunnel
cloudflared tunnel --url http://localhost:3000
# or
ngrok http 3000
The provider talks to your local server directly, so signatures pass untouched. In exchange, your local server is reachable from the internet while the tunnel runs. A cloudflared quick tunnel also gets a new URL every run, so you paste it into the provider again each time.
3. A relay
A public service receives each request and stores it. A small client on your machine picks it up and sends a copy to localhost. smee.io works this way. So does WebhookCat, which I built:
npx webhookcat listen 3000
Your machine only makes outbound connections, and you can still read the payload when your server is down or throwing errors.
Where signatures break
Most providers sign the raw request body. Verification fails if anything between the provider and your handler changes a single byte.
Body parsing. If middleware parses the JSON before your handler sees it, re-serializing it can change whitespace or key order. In Express, give the webhook route the raw body:
app.post("/webhooks/github", express.raw({ type: "application/json" }), (req, res) => {
// req.body is a Buffer here
});
Relays that rewrite the request. A relay has to pass the body through byte for byte and keep the signature header. The WebhookCat CLI drops only a short list of transport headers such as Host and Content-Length. One limit to know: WebhookCat stores the first 64 KB of a body, so a larger payload can't be verified.
Time. Stripe puts a timestamp in Stripe-Signature, and its libraries reject events older than five minutes by default. Forwarding on arrival is fine. Replaying a stored event an hour later fails, and that is by design.
Checking a GitHub signature by hand looks like this:
import crypto from "node:crypto";
function verifyGitHub(rawBody, header, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(header ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Use timingSafeEqual instead of === so the time the comparison takes doesn't reveal how many characters matched.
Which one to use
- Only Stripe: the Stripe CLI.
- The provider has to reach your server live with no extra hop: a tunnel.
- You want to see every payload, keep your machine closed, or test several providers at once: a relay.
I built WebhookCat, one of the relays above. This article was drafted by AI, and I reviewed it before publishing.
Top comments (0)