stripe-webhook-security

Stripe Webhook Security

Stripe webhooks are how a payment provider tells your backend that things happened. If they are wrong — forged, replayed, or processed twice — you ship product without payment, or charge customers twice, or skip a refund. This skill covers the patterns that prevent that.

Applies to Stripe (and largely to other PSPs with similar webhook designs: Paddle, Mollie, Adyen). Examples are Node/Express; the principles port.

When to invoke

• Wiring a new Stripe webhook endpoint
• Adding a new event type to an existing handler
• Investigating a payments incident (mismatched orders, double-charge, missing refunds)
• Migrating from test mode to live mode
• Auditing an inherited integration

The three rules

A webhook handler must do all three of these. Skipping any one is a bug.

1. Verify the signature before trusting any field
2. Be idempotent — receiving the same event twice does nothing extra
3. Use the event as a hint, not a source of truth for high-value actions

Rule 1 — Signature verification (on raw body)

Stripe signs the request with STRIPE_WEBHOOK_SECRET. Verification only works on the exact raw bytes Stripe sent — JSON-parsing first destroys the signature.

// Express — register the raw-body middleware ONLY for the webhook route
import express from 'express';
import Stripe from 'stripe';

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: '2024-12-18.acacia' });

// IMPORTANT: do not use express.json() ahead of this route
app.post(
  '/webhooks/stripe',
  express.raw({ type: 'application/json', limit: '1mb' }),
  async (req, res) => {
    const sig = req.headers['stripe-signature'] as string;
    let event: Stripe.Event;
    try {
      event = stripe.webhooks.constructEvent(
        req.body,                          // Buffer, NOT parsed
        sig,
        process.env.STRIPE_WEBHOOK_SECRET!
      );
    } catch (err) {
      // Signature invalid — do NOT log the body
      return res.status(400).send('invalid signature');
    }
    await handle(event);
    res.json({ received: true });
  }
);

// Other routes use JSON parsing normally
app.use(express.json());