Your webhook handler works. Once.
Stripe delivers twice, out of order, late, and again after a timeout. Webhook Trap replays your real events that way against your handler and fails the build when your database ends up wrong.
npx @webhooktrap/agentOpen source · self-hostable · secrets stay on your machine
webhooktrap test --fail-on high runs Run #3 against localhost:3000/webhooks/stripe. Once, Shuffled, Late and Burst pass. Twice, Retry after error, Tampered and Slow budget fail. 3 findings: F1 Critical, accepts a tampered payload; F2 High, a duplicate delivery created a second order; F3 Medium, over the 10 s budget. Exit code 1.
A finding is a failing test, with the diff that fixes it.
Each one names the deliveries that prove it, what was expected, what your handler did, and the provider doc behind it. Then the change. Run #3 found three.
F2 High · Duplicate delivery created a second order
- orders.count
- Expected
- 1
- Received
- 2
- D4 invoice.paid evt_1QK9…pjPU 200 0 → 1
- D5 invoice.paid evt_1QK9…pjPU 200 1 → 2 same event id
- D11 invoice.paid retry 200 1 → 2
Stripe may deliver the same event more than once, and retries failed or timed-out deliveries with backoff for up to 3 days in live mode. Each duplicate creates another order.Stripe docs › Webhooks › Handle duplicate events · Retry behavior
@@ app.post('/webhooks/stripe') @@ event = stripe.webhooks.constructEvent(req.body, sig, endpointSecret); ...+ // before creating the order+ const { rowCount } = await db.query(+ 'INSERT INTO processed_events (id) VALUES ($1) ON CONFLICT DO NOTHING',+ [event.id]+ );+ if (rowCount === 0) return res.sendStatus(200); // already handled await createOrder(event.data.object); res.json({ received: true });
F1 Critical · Accepts tampered payload
- D12 body
- amount_paid 2400 → 0
- Expected
- a 4xx and no change
- Received
- 200 in 167 ms · orders.count 0 → 1
Stripe signs the exact bytes it sends. If a failed check doesn't stop the request, anyone who can reach this URL can create paid orders. Late (D9) was rejected, so the timestamp check runs; the signature check probably fails into a log line.Stripe docs › Webhooks › Verify signatures
@@ app.post('/webhooks/stripe') @@ try { event = stripe.webhooks.constructEvent(req.body, req.get('stripe-signature'), endpointSecret); } catch (err) {- console.warn('signature check failed', err.message);+ return res.status(400).send('Invalid signature'); // stop here, don't log and continue }
F3 Medium · Over the 10 s budget for Stripe
- Budget
- 10 000 ms · Webhook Trap default
- D10
- 11 840 ms (+1 840 over)
- D16
- 10 420 ms (+420 over)
- Others
- median 202 ms
If Stripe times out waiting, the delivery counts as failed and is retried. Stripe doesn't publish the timeout, so these are over our default budget, not proven failures at Stripe. In this run the retry after D10 created the duplicate order in F2.Stripe docs › Webhooks › Quickly return a 2xx response
@@ case 'invoice.paid': @@ await createOrder(invoice);- await createShippingLabel(invoice);- res.json({ received: true });+ res.sendStatus(200); // acknowledge first+ await queue.add('create-label', { invoiceId: event.data.object.id });
webhooktrap scenarios
Every way a webhook can arrive. Nine scenarios, always run in this order, each one taken from what the provider's own docs say it does.
Oncen deliveriesEvery selected event once, in capture order. Sets the baseline.
Every provider
Needs the signing secret: no
Twice2 deliveriesThe first event again, 500 ms after the first delivery completes: same event id, new signature timestamp
Stripe may deliver the same event more than once.
Stripe docs › Webhooks › Handle duplicate eventsNeeds the signing secret: yes
Shuffledn deliveriesRelated events in reverse order
Stripe doesn't guarantee delivery order.
Stripe docs › Webhooks › Event orderingNeeds the signing secret: yes
Late1 deliveryValid signature, timestamp 360 s old (tolerance 300 s)
Replay protection relies on the timestamp tolerance.
Stripe docs › Webhooks › Prevent replay attacksNeeds the signing secret: yes
Retry after error2 deliveriesSends the event, then the provider's retry 2 s after it completes.
Providers retry when a delivery fails or takes too long; your handler can't tell which.
Stripe retries failed or timed-out deliveries with backoff for up to 3 days in live mode.
Stripe docs › Webhooks › Retry behaviorNeeds the signing secret: yes
Tampered1 deliveryamount_paid 2400 → 0 in the body, signed for the original body
A signature only protects you if a failed check stops the request.
Stripe docs › Webhooks › Verify signaturesNeeds the signing secret: yes
Unsigned1 deliveryThe event with every signature header removed
A handler that checks the signature only when the header is present accepts anything.
Stripe docs › Webhooks › Verify signaturesNeeds the signing secret: no
Burstmax(n,2) deliveriesEvery selected event, released together (≤ 20 ms apart)
Stripe sends related events close together, often concurrently.
Stripe docs › Webhooks › Event orderingNeeds the signing secret: yes
Slow budget1 deliveryOne more delivery after the others, measured against the budget: 10 s budget · Webhook Trap default
If Stripe times out waiting, the delivery counts as failed and is retried. Stripe doesn't publish the timeout.
Stripe docs › Webhooks › Quickly return a 2xx responseNeeds the signing secret: no
Sequence packs and test commands: later.
Real traffic, not fixtures you wrote
Capture what Stripe actually sent, scrub the personal data, commit it, and let CI replay it on every push.
# 1 Capture: point Stripe test mode at your URL https://webhooktrap.dev/c/Br7nDLk2Qm9x# 2 Scrub: personal data is replaced before it is saved customer_email jonah.reyes@example.com → customer1@example.test customer_name Jonah Reyes → Test Customer 1 hosted_invoice_url → https://invoice.stripe.test/redacted# 3 Commit $ git add webhooktrap/fixtures/stripe/invoice.paid.json# 4 CI: fail the build on High and above $ webhooktrap test --fail-on high
Secrets stay on your machine
- Sends deliveries only to targets you allow
- Keeps signing secrets on your machine (we see names, never values)
- Probe values stay on your machine. Only small counts and codes reach the server.
- Open source (AGPL-3.0). Run your own with docker compose up
Free to run yourself. If it saves you a night, Buy me a coffee
$ webhooktrap secrets list provider name value Stripe STRIPE_WEBHOOK_SECRET set stays on this machine GitHub GITHUB_WEBHOOK_SECRET set Shopify SHOPIFY_API_SECRET set Parcelbird PARCELBIRD_WEBHOOK_SECRET not set → webhooktrap secrets set parcelbird $ docker compose up # or run your own instance
Works with your coding agent
Findings come out as JSON: the type, the deliveries that prove it, and the fix in words your agent can apply and rerun.
{
"id": "F2",
"type": "duplicate_changed_state",
"severity": "high",
"title": "Duplicate delivery created a second order",
"evidence": ["D4", "D5", "D10", "D11"],
"fix": { "text": "Record event.id before creating the order and return 200 early when it is already recorded. After the fix, D5 and D11 should leave orders.count at 1." }
}Providers
- Stripe
- GitHub
- Shopify
- Standard Webhooks
Coming: Twilio, Slack
Prove your first handler in 5 minutes.
npx @webhooktrap/agent