Guide

Webhook Security Checklist for Receivers

A webhook endpoint is a public URL that changes state in your system when it is called. That makes it worth a few deliberate defences. Work through these in order.

1. Verify the signature on every request

Most providers sign each delivery with a secret you share, typically an HMAC-SHA256 of the request body. Compute the same HMAC and reject the request if it does not match. Without this, anyone who learns the URL can forge events.

2. Verify against the raw body

The signature covers the bytes that were sent. If you parse the JSON and serialise it again, whitespace and key order change and the check fails, or worse, you are tempted to skip it. Capture the raw body before any body-parsing middleware runs.

Raw body first, parse after verifying
// Express: keep the raw bytes for the webhook route only
app.post("/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body; // a Buffer
  if (!verify(rawBody, req.headers)) return res.sendStatus(400);
  const event = JSON.parse(rawBody);
  res.sendStatus(200);
});

3. Compare signatures in constant time

An ordinary string comparison returns as soon as it finds a difference, which leaks information through timing. Use crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python or hash_equals in PHP.

4. Reject stale timestamps

A valid signed request that an attacker captured can be sent again later. Schemes such as Stripe's and Slack's include a timestamp in the signed data. Reject anything more than a few minutes old.

5. Make processing idempotent

Record the event ID when you process it and ignore IDs you have seen. This protects against provider retries as much as against replay attacks. More in retries and idempotency.

6. Acknowledge first, work later

Return a 2xx as soon as the request is verified and stored, then process it from a queue. Slow endpoints cause timeouts, timeouts cause retries, and retries arrive when you are least able to handle them.

7. Treat the payload as untrusted input

Even a correctly signed payload contains data that originated with end users: names, addresses, free-text fields. Validate types, escape on output and never build queries by concatenation. Where the stakes are high, use the event as a notification and fetch the object from the provider's API to get the authoritative state.

8. Use HTTPS and keep secrets out of URLs

Register only https:// endpoints. Do not put tokens in the query string: URLs end up in logs, browser history and error reports. Signatures and headers are the right place for authentication.

9. Rotate secrets and know how to do it without downtime

Good providers let two secrets be valid during a rotation. Check both until the old one is retired. Rotate immediately if a secret ever appears in a log, a screenshot or a chat message.

Check your implementation against a real request

Capture a delivery from your provider and verify it with the signature verifier. If the verifier accepts it and your code does not, the difference is almost always item 2: the body your code hashed is not the body that was sent.

About secrets and this siteSignature verification on webhook.stream happens in your browser. Your signing secret is not transmitted to our servers or stored. Even so, prefer test-mode secrets when you experiment.