Webhook System Design
How to send HTTP callbacks to other companies' servers reliably and safely: durable events, retries with backoff, signatures, duplicates, ordering, and keeping one bad endpoint from hurting the rest.
Overview
A webhook is an HTTP request that one system sends to another when something happens. The receiver registers a URL, say https://shop.example/hooks/payments, and picks the events it cares about. When a payment succeeds, the sender POSTs a small JSON message about it to that URL. Payment providers, code hosts and online stores all use webhooks to tell their customers' systems about events.
Webhooks replace polling, where the customer asks 'anything new?' every few seconds. Polling wastes requests when nothing has changed and still learns about changes late. A webhook arrives once, soon after the event.
The hard part is that the sender does not control the receiver. The receiving server may be down, slow, returning errors, or not who it claims to be, and the network between them can drop a reply after the work was done. A webhook system is a small, durable delivery service built to cope with all of that.
What you will be able to do
- Design a delivery pipeline that never loses an event and never slows the product.
- Explain why delivery is at least once, and how receivers stay correct with duplicates.
- Choose a retry schedule, and say when to give up and what happens next.
- Sign and verify webhooks, and stop replayed messages.
- Protect the sender from slow endpoints and from URLs that point into its own network.
Key concepts
- Push instead of poll
- Transactional outbox
- At-least-once delivery
- Idempotent receivers
- Retries with backoff and jitter
- HMAC signatures
- Replay protection
- Out-of-order events
- Endpoint isolation
- SSRF protection
Interview questions
- Design a webhook delivery system for a payment provider.
- Why can't webhooks be delivered exactly once?
- How should a receiver verify that a webhook is genuine?
- A customer's endpoint has been returning 500 for six hours. What does your system do?
- How do you handle events that arrive out of order?
- What security risks does a webhook sender face?
- How would you build a receiver that stays fast under a burst of webhooks?
- How do you rotate a webhook signing secret without dropping events?
Sign up free to read the full topic
More System Design topics
Start free on Cariara · Coding problems · System design studio