Stripe Webhook Testing

1. Local app setup

Create a local webhook endpoint at: /webhooks/stripe

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

const app = express()
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.header('stripe-signature') || ''
  try {
    const event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
    console.log('stripe event:', event.type)
    res.status(200).send('ok')
  } catch (err) {
    console.error('invalid signature', err)
    res.status(400).send('invalid signature')
  }
})

app.listen(3000, () => console.log('listening on :3000'))

2. Run InstaTunnel command

instatunnel 3000 --subdomain stripe-dev

Keep a fixed subdomain so your provider dashboard URL does not keep changing.

3. Provider config fields to paste

Use the helper below to generate exact values with your chosen subdomain and path.

4. Send test event

1. Open Stripe Dashboard > Developers > Webhooks > your endpoint.
2. Use "Send test webhook" for a handled event type.
3. Confirm your local logs show the event and a 2xx response.

# Optional Stripe CLI flow
stripe listen --forward-to localhost:3000/webhooks/stripe
stripe trigger checkout.session.completed

5. Verify signature

Verify this header on every request: stripe-signature

// Stripe verifies with raw request body + endpoint secret
const event = stripe.webhooks.constructEvent(
  req.body,
  req.header('stripe-signature')!,
  process.env.STRIPE_WEBHOOK_SECRET!
)

6. Retries and idempotency

• Store Stripe event IDs and ignore duplicates.
• Return 2xx quickly, then process asynchronously.
• If you return non-2xx, Stripe retries with backoff.

7. Common failures and quick fixes