webhook-inbox
In DevelopmentA Stripe webhook receiver that survives duplicate, out-of-order and failing events
Role: Solo developer
Solo · Since Nov 2026 · Public repo
A NestJS service that verifies a Stripe signature, stores each event before processing it, applies it in order, retries failures with backoff and keeps the ones that cannot be processed in a queue you can inspect and replay.
Problem
A webhook endpoint that works in a tutorial fails quietly in production: Stripe retries, so the same event arrives twice; it does not guarantee order, so a refund can arrive before the payment it refunds; and a slow endpoint makes Stripe send it all again.
Solution
The endpoint only checks the signature over the raw body, inserts the event keyed by its Stripe id and answers 200. A worker claims ready events with UPDATE ... FOR UPDATE SKIP LOCKED and applies each one in the same transaction that marks it done. Each order remembers the date of the last event it applied, so an older one is discarded.
Not done yet
It was never connected to a real Stripe account: signatures in the tests and the simulator come from the SDK's helper with a test secret. It handles three event types, the orders table is a stand-in, I did not measure throughput and there are no metrics or traces.
Architecture highlights
- 20 simultaneous deliveries of the same event leave one row and exactly one response reporting it as new. Removing ON CONFLICT breaks both duplicate tests
- A refund processed before its payment still ends as refunded, and events in the same second are resolved by state so the result does not depend on arrival order. Removing the ordering guard breaks three tests
- Retries wait 5 s times 2 to the attempt, capped at one hour with full jitter, and after 6 attempts the event goes to a dead queue behind a token-protected endpoint that can replay it
- I removed SKIP LOCKED to check my tests and the three-worker test still passed: uniqueness comes from the UPDATE re-evaluating its WHERE, and SKIP LOCKED only avoids waiting. I fixed my own code comment and added a test with a row held by another transaction, which does fail without it
- 31 tests run against a real PostgreSQL container, because ON CONFLICT, SKIP LOCKED and transactions are database behavior a mock cannot show