How to handle webhooks in Stripe

1const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
2const express = require('express');
3const app = express();
4
5// CRITICAL: webhook route must use express.raw(), not express.json()
6app.post('/webhook',
7  express.raw({ type: 'application/json' }),
8  (req, res) => {
9    const sig = req.headers['stripe-signature'];
10    let event;
11
12    try {
13      event = stripe.webhooks.constructEvent(
14        req.body,              // Raw body buffer
15        sig,                   // Stripe-Signature header
16        process.env.STRIPE_WEBHOOK_SECRET  // whsec_ from Dashboard
17      );
18    } catch (err) {
19      console.error('Webhook signature verification failed:', err.message);
20      return res.status(400).send(`Webhook Error: ${err.message}`);
21    }
22
23    console.log('Verified event:', event.type, event.id);
24    res.json({ received: true });
25  }
26);
27
28// Other routes can use express.json() normally
29app.use(express.json());
30
31app.listen(3000, () => console.log('Webhook server on port 3000'));

1function handleEvent(event) {
2  switch (event.type) {
3    // Payment events
4    case 'payment_intent.succeeded': {
5      const pi = event.data.object;
6      console.log(`Payment ${pi.id}: $${pi.amount / 100} ${pi.currency}`);
7      // Fulfill the order
8      break;
9    }
10    case 'payment_intent.payment_failed': {
11      const pi = event.data.object;
12      console.log(`Payment failed: ${pi.id}`, pi.last_payment_error?.message);
13      // Notify the customer
14      break;
15    }
16
17    // Subscription events
18    case 'customer.subscription.created':
19      console.log('New subscription:', event.data.object.id);
20      break;
21    case 'customer.subscription.deleted':
22      console.log('Subscription canceled:', event.data.object.id);
23      // Revoke access
24      break;
25    case 'invoice.payment_failed':
26      console.log('Invoice payment failed:', event.data.object.id);
27      // Send dunning email
28      break;
29
30    // Dispute events
31    case 'charge.dispute.created':
32      console.log('Dispute opened:', event.data.object.id);
33      // Alert your team
34      break;
35
36    // Connect events
37    case 'account.updated': {
38      const acct = event.data.object;
39      console.log(`Account ${acct.id}: charges=${acct.charges_enabled}`);
40      break;
41    }
42
43    default:
44      console.log(`Unhandled event type: ${event.type}`);
45  }
46}

1// Simple in-memory set for deduplication (use Redis or DB in production)
2const processedEvents = new Set();
3
4function processEventIdempotently(event) {
5  // Check if we have already processed this event
6  if (processedEvents.has(event.id)) {
7    console.log(`Event ${event.id} already processed, skipping`);
8    return;
9  }
10
11  // Process the event
12  handleEvent(event);
13
14  // Mark as processed
15  processedEvents.add(event.id);
16
17  // Clean up old events (keep last 10,000)
18  if (processedEvents.size > 10000) {
19    const iterator = processedEvents.values();
20    processedEvents.delete(iterator.next().value);
21  }
22}
23
24// In production, use a database:
25// INSERT INTO processed_events (event_id, processed_at)
26// VALUES ($1, NOW())
27// ON CONFLICT (event_id) DO NOTHING
28// RETURNING event_id

1// After registering in the Dashboard, you receive a signing secret:
2// whsec_abc123...
3//
4// Store it as an environment variable:
5// STRIPE_WEBHOOK_SECRET=whsec_abc123...
6//
7// Common events to subscribe to:
8// - payment_intent.succeeded
9// - payment_intent.payment_failed
10// - customer.subscription.created
11// - customer.subscription.updated
12// - customer.subscription.deleted
13// - invoice.payment_failed
14// - invoice.paid
15// - charge.dispute.created
16// - charge.refunded
17// - account.updated (for Connect)
18// - checkout.session.completed
19
20console.log('Register your endpoint at:');
21console.log('Dashboard → Developers → Webhooks → Add endpoint');
22console.log('URL: https://yoursite.com/webhook');
23console.log('Copy the signing secret to STRIPE_WEBHOOK_SECRET env var');

1app.post('/webhook',
2  express.raw({ type: 'application/json' }),
3  async (req, res) => {
4    const sig = req.headers['stripe-signature'];
5    let event;
6
7    try {
8      event = stripe.webhooks.constructEvent(
9        req.body, sig, process.env.STRIPE_WEBHOOK_SECRET
10      );
11    } catch (err) {
12      return res.status(400).send(`Webhook Error: ${err.message}`);
13    }
14
15    // Respond immediately — Stripe retries if no 2xx within 20 seconds
16    res.json({ received: true });
17
18    // Process the event asynchronously
19    try {
20      await processEventAsync(event);
21    } catch (err) {
22      console.error(`Error processing ${event.type}:`, err.message);
23      // Log to error tracking (Sentry, etc.)
24      // The event will be retried by Stripe if needed
25    }
26  }
27);
28
29async function processEventAsync(event) {
30  // Your business logic here
31  // Can take as long as needed since we already responded 200
32  handleEvent(event);
33}