Stripe Webhook Best Practices: A Complete Guide

Stripe webhooks are essential for building robust payment integrations. They notify your application of events like successful payments, subscription changes, and refunds.

Always Verify Webhook Signatures

Stripe signs every webhook with a unique signature. Always verify this signature to ensure the webhook is legitimate:

const stripe = require('stripe')('sk_...');
const endpointSecret = 'whsec_...';

app.post('/webhook', (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret);
  } catch (err) {
    return res.status(400).send('Webhook signature verification failed');
  }

  // Handle the event
  res.json({ received: true });
});

Handle Events Idempotently

Stripe may send the same webhook multiple times. Always check if you've already processed an event:

const processedEvents = new Set();

if (processedEvents.has(event.id)) {
  return res.json({ received: true });
}

processedEvents.add(event.id);
// Process the event...

Return 200 Quickly

Stripe expects a 2xx response within 20 seconds. Process webhooks asynchronously:

app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.json({ received: true });

  // Process asynchronously
  await processWebhookAsync(event);
});

Use a Webhook Proxy

For production applications, use a webhook proxy like HookWatch to:

• Never miss a webhook during deployments
• Automatically retry failed deliveries
• Debug issues with full webhook logs
• Get alerts when something goes wrong

Key Events to Handle

For most Stripe integrations, handle these events:

• checkout.session.completed - Payment successful
• customer.subscription.updated - Subscription changed
• customer.subscription.deleted - Subscription cancelled
• invoice.payment_failed - Payment failed

Build reliable payment integrations by following these best practices.