Test Stripe Webhooks Locally

From a stuck handler to a live Stripe delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 4242. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL — something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3In the Stripe Dashboard go to Developers → Webhooks → Add endpoint and paste your LocalCan URL with your path, e.g. https://your-app-12.localcan.dev/webhook. Select the events to send, then copy that endpoint’s signing secret (whsec_…).
4. 4Fire one: stripe trigger payment_intent.succeeded, or open any event in the Dashboard and click Resend. Heads-up: stripe listen prints its own whsec_ — different from this endpoint’s secret.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body — expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

Header

Stripe-Signature

Algorithm

HMAC-SHA256, hex-encoded

What's signed

Stripe signs the string {t}.{raw body} — the t= value from the header, a literal dot, then the exact bytes of the request body. The result is the v1= hex digest. Parse the JSON before reading the raw body and the signature can never match.

Secret

The endpoint signing secret (whsec_…) from the Dashboard endpoint. stripe listen prints a different whsec_… for events it forwards — use the one that matches how the event is being sent.

import express from 'express'
import Stripe from 'stripe'

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY)
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET // whsec_...

const app = express()

// Stripe needs the RAW body — mount express.raw BEFORE any JSON parser.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature']
  try {
    // constructEvent recomputes HMAC-SHA256 over "{t}.{body}" and checks the
    // 5-minute tolerance. Throws on a bad signature, wrong secret, or old timestamp.
    const event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret)
    if (event.type === 'payment_intent.succeeded') {
      // handle it
    }
    res.json({ received: true })
  } catch (err) {
    res.status(400).send('Webhook Error: ' + err.message)
  }
})