Webhook Signature Verification: How Stripe, GitHub, Slack and Shopify Sign Events, and How to Check One

What does a webhook signature prove?

A valid signature proves two things: the sender holds the same secret as you, and the bytes were not changed on the way. It does not prove the event is new: a request captured once still carries a valid signature when it is sent again. That is why the timestamp and delivery id checks exist.

HMAC

A hash computed with a secret key, defined in RFC 2104. Only someone who holds the key can produce the same value for the same message. Five of the six schemes below use HMAC with SHA-256; Twilio uses HMAC with SHA-1.

Signing secret

The key you and the provider share, shown when you create the endpoint. Stripe's starts with whsec_; the Standard Webhooks spec uses the same prefix.

Signed content

The exact string the sender fed into the HMAC: sometimes the body alone, sometimes a timestamp and an id joined to it. You must rebuild it byte for byte.

Replay

Sending a captured, correctly signed request again. The signature still matches, so only a timestamp limit or a list of seen ids stops it.

Constant-time comparison

A comparison that takes the same time whether the first byte differs or the last one does, so response times reveal nothing about the expected signature.

How do Stripe, GitHub, Slack, Shopify and Twilio sign their webhooks?

All six schemes below put a signature in a header, and every one of them supports an HMAC. They differ in what goes into it. Read the row for your provider before you write any code: a verifier that hashes the wrong string fails on every request.

Sources: each provider's verification page, linked in the first column and listed at the end. For JSON bodies, Twilio adds a bodySHA256 query parameter holding a SHA-256 hash of the raw body (Twilio webhooks security).

How do you verify a webhook signature in Node.js?

The function below checks a request in the Standard Webhooks format. For another provider, change three things: the header names, the signed string (the table above) and the encoding of the signature (hex or base64). The order of the checks stays the same.

1. Read the raw body as text, before any JSON parser touches it. In a Fetch API handler, such as a Next.js route handler, await request.text() gives it to you (MDN).
2. Check the timestamp first: it is cheap and stops replays of old requests.
3. Rebuild the signed string and compute the HMAC with your secret.
4. Compare in constant time with every signature in the header.
5. Skip ids you have already processed, then answer quickly and do the work in a queue.

import { createHmac, timingSafeEqual } from 'node:crypto'

const TOLERANCE_SECONDS = 5 * 60

// Standard Webhooks format: webhook-id, webhook-timestamp, webhook-signature.
export function verifyWebhook(secret, headers, rawBody) {
  const id = headers.get('webhook-id')
  const timestamp = headers.get('webhook-timestamp')
  const signatures = headers.get('webhook-signature')
  if (!secret || !id || !timestamp || !signatures) return false

  // Too old, too far in the future, or not a number: reject.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp))
  if (!(age <= TOLERANCE_SECONDS)) return false

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64')
  const expected = createHmac('sha256', key)
    .update(id + '.' + timestamp + '.' + rawBody)
    .digest()

  // The header can hold several signatures while a secret is rotated.
  return signatures.split(' ').some((entry) => {
    const [version, value] = entry.split(',')
    if (version !== 'v1' || !value) return false
    const received = Buffer.from(value, 'base64')
    return received.length === expected.length && timingSafeEqual(received, expected)
  })
}

// A route handler: read the body as text, verify it, and only then parse it.
export async function POST(request) {
  const rawBody = await request.text()
  if (!verifyWebhook(process.env.WEBHOOK_SECRET, request.headers, rawBody)) {
    return new Response('invalid signature', { status: 401 })
  }
  const event = JSON.parse(rawBody)
  // Skip it if this webhook-id was already processed, queue the work, answer fast.
  return new Response(null, { status: 204 })
}

The length check before timingSafeEqual is not optional: Node.js throws an error when the two buffers have different byte lengths (Node.js crypto docs). An HMAC-SHA256 is always 32 bytes, so checking the length first reveals nothing. request.text() always decodes the body as UTF-8 (MDN); if a provider may send other bytes, read request.arrayBuffer() and hash the bytes instead.

Why must the signature comparison take constant time?

A plain == on two strings usually stops at the first byte that differs. That makes a wrong guess answer a little faster when its first bytes are wrong than when they are right, and timing attacks build on that difference. GitHub's docs say "Never use a plain == operator" and point to crypto.timingSafeEqual (GitHub); Stripe asks for a constant-time comparison "to protect against timing attacks" (Stripe).

Illustration with 8 made-up bytes; the third byte differs. A real HMAC-SHA256 is 32 bytes. Node.js adds that timingSafeEqual does not make the code around it timing-safe (Node.js crypto docs), so do not branch on partial matches before calling it.

How long should a webhook timestamp stay valid?

Five minutes is the common answer: it is the default tolerance of Stripe's libraries and the limit in Slack's example. Stripe warns against a tolerance of 0, which "disables the recency check entirely". The Standard Webhooks spec asks for "some allowable tolerance" and names no number. A timestamp limit is only one of several clocks a webhook receiver runs on:

Two of these clocks pull against each other. A retry arrives long after the original send, so a receiver that checks timestamps would reject it if it carried the old one. Stripe handles this by generating "a new signature and timestamp for the new delivery attempt" (Stripe). So neither the signature nor the timestamp can tell you a request is a repeat. Stripe says to log the event ids you have processed and skip them, and to check the object id in data.object too, because it sometimes sends two separate events for one change.

Which mistakes make webhook verification fail?

How do you rotate a webhook signing secret without losing events?

Rotation works because a signature header can carry more than one signature. Stripe can send several v1 signatures and keeps "the previous secret active for up to 24 hours"; the Standard Webhooks header is "a space delimited list of signatures" so that rotation needs no downtime.

1. Accept both secrets

   Deploy a verifier that passes when any signature in the header matches the old or the new secret.

2. Roll the secret at the provider

   Expect a lag: Shopify says it "can take up to an hour" before the new secret is used for the digest.

3. Watch the failures

   Count rejected deliveries per endpoint. A rise right after the roll usually means a server still has only the old secret.

4. Remove the old secret

   After the provider's window has passed (24 hours at Stripe), delete it from your config and your secret store.

Sending webhooks from your own product?

Webhook signature questions