Skip to content

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/agent
See an example run ›

Open source · self-hostable · secrets stay on your machine

~/code/brindle-app
Animated terminal run. Its text version follows the terminal.
maya-mbpconnected · v0.9.2Run #3running

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.

FAIL Twice · Retry after error

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

src/webhooks/stripe.js+5
@@ 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 });
After the fix, D5 and D11 should leave orders.count at 1. Run #4: Passed · 1 Info · exit 0

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 events

Needs the signing secret: yes

Shuffledn deliveriesRelated events in reverse order

Stripe doesn't guarantee delivery order.

Stripe docs › Webhooks › Event ordering

Needs 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 attacks

Needs 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 behavior

Needs 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 signatures

Needs 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 signatures

Needs 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 ordering

Needs 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 response

Needs 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.

capture → scrub → commit → CI
# 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

agent · maya-mbp
$ 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.

findings[] · Run #3
{
  "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