Unit 3 — at-least-once delivery, backoff, signatures, and dead letters
Webhooks & Reliable Delivery
When the charge from Unit 1 succeeds and the ledger entry from Unit 2 is posted, the merchant's own systems need to know — to ship the order, send a receipt, provision access. They are not polling your API millions of times a minute. You push them an event: a webhook.
The hard part is not sending the HTTP request. It is guaranteeing the event eventually arrives even when the merchant's endpoint is down, slow, or flaky — without melting their server or yours. This unit builds reliable, at-least-once webhook delivery with exponential backoff, signature verification, and a dead-letter queue.
Sub-unit 1 of 7
The product problem
Functional
- Deliver every payment event to the merchant's registered endpoint.
- Retry automatically on failure with increasing delays.
- Track per-event delivery state (pending, delivered, exhausted).
- Let merchants verify the event genuinely came from us.
Non-functional
- At-least-once delivery — never silently drop an event.
- p99 under 5s from event emission to the first delivery attempt.
- Retry for up to 72 hours before giving up.
- A slow or dead endpoint must not exhaust sender resources.
Constraints
- Merchant endpoints are untrusted, can be down for hours, and may be slow.
- The network can deliver duplicates and reorder events.
- A 2xx response does not guarantee the merchant actually processed the event.
Finished reading? Mark this sub-unit complete to unlock the next.