Design a webhook delivery system
PremiumAPI designMedium
- Webhooks
- At least once delivery
- HMAC signatures
Quick answer
This API design interview question asks you to design a webhook delivery system. Aim for a design that exposes a clear, consistent and safe interface, then explain the resources, requests, responses and error handling. Interviewers want to see how you name resources, version the interface and handle failure cases.
The problem
Design a webhook delivery system like the ones Stripe and GitHub run: customers register HTTPS endpoints and the platform POSTs signed events to them when something happens. The hard parts are reliable delivery with retries, proof that each request is genuine, and keeping one slow endpoint from delaying everyone else.
Events cover things like an order was paid, a document was signed or a user was deleted, and customers pick the event types they want for each endpoint. Developers also need tools to see what was sent and to resend it.
What must a webhook delivery system do?
- Delivery: POST the event as JSON to the endpoint. A 2xx within 10 seconds counts as delivered; timeouts, connection errors and retryable responses are retried with backoff for up to 3 days.
- Verification: The receiver can prove the request came from the platform and was not replayed.
How well must it do it?
- Reliability: At-least-once delivery; the receiver must be able to deduplicate.
- Ordering: Best effort within one object (order.paid before order.refunded for the same order); no global ordering promise.
What scale should you design for?
Use these numbers in your estimates.
The scale numbers unlock with this questionUnlock
Key concepts
- Webhooks
- At least once delivery
- HMAC signatures
- Exponential backoff
- Event ordering
- Replay protection
How you’ll practise
- Use cases
- Resources
- Endpoints
- Errors, auth and limits
- Versioning
- Wrap-up
Lala, personalized to you, gives a hint when you ask and reviews your design when you are ready.
What do interviewers look for?
In any API design round.
- Starts from the clients and the use cases
- Names resources and operations consistently
- Defines request and response shapes and status codes
- Covers authentication, rate limits and idempotency
- Plans pagination, filtering and versioning
- Explains how clients learn about and recover from errors
Questions people ask about this interview question
- Which design type is this question?
- It is an API design question. You design a webhook delivery system and explain your choices the way you would in an interview.
- Is this question asked at entry level?
- It is marked Medium. Entry-level engineers can practise it, but it expects you to reason about requirements and trade-offs, not only list components.
- What should I cover first?
- Start with the clients, the main use cases and the resources they need. Agree on scope with the interviewer before you design anything.
- Can I practise it for free?
- It is a premium question. Sign up and unlock it once for 10 credits; it then stays unlocked. When you finish, Lala, your personalized AI mentor, can review your design for 30 credits.
Related questions
Updated · Written by the SevyDevy team