Stripe Guides de test webhook

Replay + helper signature (dashboard)

Open /dashboard or /dashboard/tunnels and use Webhook Command Center for this provider. It gives one-click replay and signature verification helpers.

instatunnel webhook verify --provider stripe --secret-env STRIPE_WEBHOOK_SECRET

curl -i -X POST "https://YOUR-SUBDOMAIN.instatunnel.my/webhooks/stripe" -H "Content-Type: application/json" --data-binary @sample-stripe.json

Required signature header: stripe-signature

1. Setup app locale

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. Lancer InstaTunnel

instatunnel 3000 --subdomain stripe-dev

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

3. Champs provider a coller

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

4. Envoyer un evenement de test

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. Verifier la 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. Retrys et idempotence

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

7. Echecs courants et corrections rapides