GuidesE-commerce

Reliable Stripe webhooks: signatures, duplicates, ordering and retries

By the Banzai Labs teamUpdated on 3 min read

StripeSignatureAlready done?200 replyProcessingResent until receivedVerify, deduplicate, reply fast, process after
Each Stripe event is verified, deduplicated, acknowledged right away, then processed.

The four rules

  1. 1VerifyThe signature, on the raw body, with the endpoint secret.
  2. 2DeduplicateThe event ID is stored; a duplicate is ignored.
  3. 3Answer fastAn immediate 200; heavy work goes to a queue.
  4. 4Read backWhen the order is in doubt, ask the Stripe API.

The endpoint

export async function POST({ request }: { request: Request }) {
  const raw = await request.text();
  const sig = request.headers.get('stripe-signature')!;
  let event;
  try {
    event = stripe.webhooks.constructEvent(raw, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('invalid signature', { status: 400 });
  }
  const isNew = await db.events.insertIfAbsent(event.id); // unique constraint
  if (isNew) await queue.add(event); // async processing
  return new Response('ok');
}

The traps

Trap Consequence Fix
JSON body rewritten Signature rejected Read the raw text
Long work before answering Stripe retries, duplicates Answer, then process
No duplicate check Order created twice Unique ID in the database
Assuming event order Inconsistent state Read the object back from the API

Listen only to what you need

In the dashboard, subscribe the endpoint only to the events you handle (checkout.session.completed, invoice.paid, customer.subscription.deleted…).

Before this: Stripe Checkout. The basics: what a webhook is.

Frequently asked questions

Why does signature verification fail?
Almost always because the request body was transformed (JSON parsed then re-serialised) before verification. You need the raw body, byte for byte.
What happens if my server is down?
Stripe retries for several days with growing delays. Missed events stay visible in the dashboard.
How do I test locally?
With the Stripe CLI: stripe listen --forward-to your local address, then stripe trigger to fire an event.

Read next

All guides