Webhooks in Stripe

This chapter follows Custom payment forms with the Payment Element.

Webhooks are HTTP POST requests from Stripe to your server. Each payload wraps an Event—checkout.session.completed, payment_intent.succeeded, and dozens of others. Subscriptions and asynchronous payment methods require webhooks; one-time Checkout integrations should use them too so fulfillment survives closed browser tabs.

Events and endpoint configuration

Register an endpoint in the Dashboard (Developers → Webhooks) or via API. Stripe sends JSON with a Stripe-Signature header. Store the signing secret (whsec_...) in STRIPE_WEBHOOK_SECRET.

Select events you handle—start with payment and subscription types you act on. Unused events add noise and load.

Verify signatures in Express

The raw body bytes must be available for signature verification. Register the webhook route before express.json():

1
import express from 'express';
2
import { handleWebhook } from './routes/webhook.js';
3
import { createCheckoutSession } from './routes/checkout.js';
4

5
const app = express();
6

7
app.post(
8
  '/webhook',
9
  express.raw({ type: 'application/json' }),
10
  handleWebhook,
11
);
12

13
app.use(express.json());
14
app.post('/create-checkout-session', createCheckoutSession);

1
import { stripe } from '../stripe-client.js';
2

3
const handledEvents = new Set();
4

5
export function handleWebhook(req, res) {
6
  const sig = req.headers['stripe-signature'];
7
  let event;
8

9
  try {
10
    event = stripe.webhooks.constructEvent(
11
      req.body,
12
      sig,
13
      process.env.STRIPE_WEBHOOK_SECRET,
14
    );
15
  } catch (err) {
16
    console.error('Webhook signature verification failed.', err.message);
17
    return res.sendStatus(400);
18
  }
19

20
  if (handledEvents.has(event.id)) {
21
    return res.json({ received: true });
22
  }
23

24
  switch (event.type) {
25
    case 'checkout.session.completed':
26
      fulfillCheckout(event.data.object);
27
      break;
28
    case 'checkout.session.async_payment_succeeded':
29
      fulfillCheckout(event.data.object);
30
      break;
31
    case 'payment_intent.succeeded':
32
      break;
33
    case 'invoice.paid':
34
      break;
35
    case 'invoice.payment_failed':
36
      break;
37
    case 'customer.subscription.updated':
38
    case 'customer.subscription.deleted':
39
      break;
40
    default:
41
      break;
42
  }
43

44
  handledEvents.add(event.id);
45
  res.json({ received: true });
46
}
47

48
function fulfillCheckout(session) {
49
  if (session.payment_status === 'unpaid') return;
50
  const userId = session.client_reference_id ?? session.metadata?.appUserId;
51
  console.log('Grant access for', userId, session.id);
52
}

Return 2xx quickly; heavy work can enqueue a job. Stripe retries non-2xx responses for up to several days.

Idempotent handlers

Stripe retries the same event.id if your server times out or returns 5xx. Persist processed event ids (database or cache) instead of an in-memory Set in production. Handlers should be safe to run twice: upsert order status, do not double-ship.

Ordering is not guaranteed across unrelated events. Design state machines that tolerate invoice.paid arriving before a related customer.subscription.updated.

Key event types

Use event.data.object as the Session, PaymentIntent, Invoice, or Subscription payload.

Local testing with the CLI

Forward events to your dev server:

1
stripe listen --forward-to localhost:4242/webhook

The CLI prints a webhook signing secret for that session—put it in STRIPE_WEBHOOK_SECRET while testing.

Trigger fixtures without clicking through UI:

1
stripe trigger checkout.session.completed
2
stripe trigger invoice.payment_failed

Combine with test Checkout payments to see the full pipeline.

Security checklist

• Verify every request with constructEvent; reject missing or invalid signatures.
• Use HTTPS in production; restrict endpoint to POST from Stripe IP ranges only as defense in depth (signature verification is the real gate).
• Do not expose webhook routes to CSRF from browsers—Stripe server POSTs JSON, not your users’ cookies for state-changing app actions.
• Rotate signing secrets through Dashboard and env vars without dropping events—support two secrets briefly during cutover if needed.

Next: Subscriptions in Stripe.