GuidesE-commerce
Reliable Stripe webhooks: signatures, duplicates, ordering and retries
The four rules
- 1VerifyThe signature, on the raw body, with the endpoint secret.
- 2DeduplicateThe event ID is stored; a duplicate is ignored.
- 3Answer fastAn immediate 200; heavy work goes to a queue.
- 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.