Stripe webhook signature verification failed — find why

Debug your Stripe signature

Stripe is selected by default. The HMAC is computed in your browser with WebCrypto — your whsec_ never leaves the tab.

Anatomy of the Stripe-Signature header

Every Stripe webhook arrives with one header that looks like this. Each comma-separated field has a job:

Stripe-Signature: t=1614556800,
  v1=5257a869e7ecebeda32affa62cdca3fa51cad7414a563a8c6e3c4b41c2b7f2c8,
  v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39

The signed string is `${t}.${rawBody}` — not the body alone. Miss the t. prefix in a hand-rolled verifier and every signature fails, even with the right secret.

The 6 root causes, in the order to check them

Ranked by how often they're the culprit. Each has a tell that separates it from the others.

The raw-body fix, framework by framework

Cause #1 is almost always this: your web framework read, parsed, and re-serialised the JSON before constructEvent saw it. Re-serialised JSON has different whitespace, so the HMAC no longer matches. Here's how to hand each framework the untouched bytes.

// The webhook route MUST come before express.json()
app.post(
  '/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    const event = stripe.webhooks.constructEvent(
      req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
    );
    res.json({ received: true });
  }
);
app.use(express.json()); // everything else

export async function POST(req: Request) {
  const body = await req.text();            // raw, untouched
  const sig = req.headers.get('stripe-signature')!;
  const event = stripe.webhooks.constructEvent(
    body, sig, process.env.STRIPE_WEBHOOK_SECRET!
  );
  return Response.json({ received: true });
}

import { buffer } from 'micro';
export const config = { api: { bodyParser: false } };

export default async function handler(req, res) {
  const raw = await buffer(req);
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(
    raw, sig, process.env.STRIPE_WEBHOOK_SECRET
  );
  res.json({ received: true });
}

Paste the exact bytes into the debugger above: if the signature only matches once you strip a trailing newline or a re-encoded field, the body was mutated in transit — not your secret.

Test mode vs live mode: the secret that looks right but isn't

Stripe hands you three different whsec_ values and they're easy to cross. First, the test endpoint's secret, shown in the Dashboard while you're in test mode. Second, the live endpoint's secret — a separate value on the same endpoint switched to live. Third, the CLI secret that stripe listen prints, different again and only valid for events forwarded by that session. All three produce a valid-looking HMAC, so the error is the same generic No signatures found — nothing says mode mismatch. The tell: test payments verify, real ones 400. Fix: read the secret from the exact endpoint, in the exact mode, that's receiving the traffic.

The 5-minute replay window everyone forgets

constructEvent doesn't only check the HMAC — it rejects any event whose t= timestamp is more than 300 seconds old, throwing Timestamp outside the tolerance zone. This bites when you replay a captured event hours later, or when your server clock has drifted. The signature is perfectly valid; it's the age that fails. The debugger above shows the timestamp age so you can tell a stale replay from a real signature mismatch. If you genuinely need a longer window, constructEvent takes a fourth tolerance argument in seconds — but fix the clock first.

Is it your handler or your secret? Generate a known-good event

When the debugger says the secret is right but prod still 400s, the bug is in how your handler reads the body. Isolate it: our Signer generates a Stripe-signed payload with a secret you control, so you can POST a guaranteed-valid event straight at your local handler. If it passes, your verification code is fine and the problem is the secret or the middleware. If it fails, the handler is mutating the body — jump back to the raw-body table above.

Diagnostic checklist

Run these in order the next time constructEvent throws.

1. Paste the failing whsec_, raw body and Stripe-Signature into the debugger above — it names the cause before you read further.
2. Confirm the body reaching constructEvent is the untouched raw string, not a parsed-and-re-serialised object.
3. Copy the signing secret straight from the endpoint's page in the Dashboard — not from stripe listen, not from another endpoint.
4. Check you're using the live secret for live traffic and the test secret for test traffic.
5. Log req.headers['stripe-signature'] and confirm it's present and not truncated by a proxy.
6. Check the event's t= timestamp isn't older than 5 minutes (stale replay or clock drift).

Capture and replay the real failing event

Still stuck? Point Stripe at a Webhook Toolkit Relay or capture URL, catch the exact request that's failing, and inspect the raw body and headers byte-for-byte — then replay it against your handler as many times as you need without waiting for another live event.

Veelgestelde vragen