Stripe Webhook Setup Guide

What Are Stripe Webhooks?

Stripe uses webhooks to notify your application when events happen in your account — a payment succeeds, a subscription renews, a dispute is opened. Instead of polling the Stripe API, your app receives an HTTP POST with a JSON payload the moment something occurs.

Common Stripe webhook event types:

Setting Up Your Endpoint

Create an HTTP POST route that accepts Stripe's JSON payloads. Here's a minimal Node.js Express example:

const express = require('express');
const app = express();

// Important: use raw body for signature verification
app.post('/webhook/stripe',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = JSON.parse(req.body);

    switch (event.type) {
      case 'payment_intent.succeeded':
        const paymentIntent = event.data.object;
        console.log('Payment succeeded:', paymentIntent.id);
        // Fulfill the order, update DB, send receipt...
        break;
      case 'invoice.payment_failed':
        console.log('Invoice payment failed:', event.data.object.id);
        // Notify customer, retry logic...
        break;
      default:
        console.log('Unhandled event type:', event.type);
    }

    res.status(200).json({ received: true });
  }
);

app.listen(3000, () => console.log('Webhook server on port 3000'));

Key points: always return a 200 response quickly. Process heavy work asynchronously (queue, background job). Stripe retries on non-2xx responses for up to 3 days.

Verifying Stripe Signatures

Never trust a webhook payload without verifying its signature. Stripe signs every webhook with your endpoint secret (starts with whsec_). Here's how:

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

app.post('/webhook/stripe',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;

    try {
      event = stripe.webhooks.constructEvent(
        req.body,    // raw body, NOT parsed JSON
        sig,
        endpointSecret
      );
    } catch (err) {
      console.error('Signature verification failed:', err.message);
      return res.status(400).send('Webhook signature verification failed');
    }

    // Event is verified — safe to process
    console.log('Verified event:', event.type);
    res.status(200).json({ received: true });
  }
);

Critical: pass the raw request body to constructEvent, not parsed JSON. If you use express.json() middleware globally, it will break verification. Use express.raw({ type: 'application/json' }) on the webhook route specifically.

Testing with SDNBros

During development you need a public URL that Stripe can reach. Here's the fastest path:

1. Open the SDNBros Webhook Tester — you get a public endpoint URL instantly, no signup required.
2. In the Stripe Dashboard, go to Developers > Webhooks > Add endpoint. Paste your SDNBros URL.
3. Select the events you want (e.g. payment_intent.succeeded, checkout.session.completed).
4. Trigger a test event using Stripe's "Send test webhook" button, or run stripe trigger payment_intent.succeeded from the Stripe CLI.
5. Switch back to SDNBros — you'll see the event arrive in real time with full headers, body, and timing. SDNBros auto-detects it as a Stripe webhook and shows the event type.

For local development, use sdnbros tunnel to forward webhooks from your SDNBros endpoint directly to localhost:3000.

Monitoring in Production

In production, webhook failures are silent killers — a missed invoice.payment_failed event means a churned customer you never knew about. Set up proper monitoring:

• Forward production webhooks through SDNBros — point Stripe at your SDNBros project URL, which forwards to your server. Every event is logged, searchable, and replayable.
• Failure alerts — SDNBros sends digest emails when deliveries fail, with root-cause diagnosis ("server returned 503 — upstream timeout").
• Replay failed events — when you fix the bug, replay the failed Stripe events from SDNBros with one click instead of asking Stripe to resend.
• Security review — use the manual webhook security checklist to review signature verification, HTTPS, replay protection, and response handling.

Create a free SDNBros account to start monitoring your Stripe webhooks in production.