Stripe Webhook Signature Verification

Stripe Webhook Signature Verification

Concept of the skill

What it is: The security check that proves an incoming Stripe webhook was signed by Stripe before any payment logic runs. Mental model: The raw request body, signature header, and webhook secret form one verification tuple; change any part and the event is untrusted. Why it exists: Webhook routes are public endpoints that can trigger billing and fulfillment, so authenticity has to be established before routing. What it is NOT: It is not payment-event routing, general HTTP signature validation, or Stripe API usage outside webhook delivery. Adjacent concepts: HMAC verification, raw request bodies, replay tolerance, idempotency keys. One-line analogy: It is the seal check before opening the payment envelope. Common misconception: Parsing JSON first is harmless; transforming the raw bytes invalidates the signature comparison.

Coverage

• The raw-body requirement — why stripe.webhooks.constructEvent() requires the unparsed Buffer from the request body, and how Next.js App Router routes expose it via request.arrayBuffer()
• HMAC-SHA256 verification — how constructEvent(rawBody, signature, secret) reconstructs and compares the Stripe signature internally
• Replay protection — the 300-second tolerance window Stripe checks against the t= timestamp embedded in the stripe-signature header; when to tighten it
• Environment-specific secrets — STRIPE_WEBHOOK_SECRET for production vs whsec_... from the Stripe CLI --forward-to session in development; why they must never be swapped
• Idempotency key pattern — recording the event.id in Postgres before processing so a retried delivery does not double-charge or double-fulfill

Philosophy of the skill

A webhook that skips signature verification is an unauthenticated public endpoint that can trigger payment processing. The verification step is load-bearing security, not a convenience check. Stripe's SDK makes verification a single call, but two failure modes are common in practice: the request body gets parsed (by a body-parser middleware) before the raw bytes reach the verification call, which silently corrupts the HMAC comparison; and the wrong webhook secret is loaded from environment variables, producing a 400 that is hard to distinguish from a replay rejection. Both failures look the same to the caller — a rejected webhook — and both are invisible until a real event is dropped.

Verification

1. Confirm raw body access. In Next.js App Router: const rawBody = Buffer.from(await request.arrayBuffer()). Do NOT pass await request.json() or await request.text() — both transform the bytes.

2. Retrieve and verify.

   import Stripe from "stripe";
   const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
   
   const sig = request.headers.get("stripe-signature") ?? "";
   let event: Stripe.Event;
   try {
     event = stripe.webhooks.constructEvent(
       rawBody,
       sig,
       process.env.STRIPE_WEBHOOK_SECRET!
     );
   } catch (err) {
     return Response.json({ error: "Signature verification failed" }, { status: 400 });
   }
   

3. Check idempotency before processing.

   INSERT INTO webhook_events (event_id, processed_at)
   VALUES ($1, now())
   ON CONFLICT (event_id) DO NOTHING
   RETURNING event_id;
   

   If the RETURNING clause returns no rows, the event was already processed — return 200 immediately without re-running side effects.

4. Route the verified event to payment-provider-router.

Failure Mode Reference

Do NOT Use When