How do webhooks work and what are the delivery guarantees?
Answer
Webhooks are reverse APIs — instead of the client polling for updates, the server pushes HTTP POST requests to a client-registered callback URL when events occur. Example: GitHub sends a webhook POST to your CI server when a commit is pushed. The client registers the webhook URL via the API: POST /webhooks { "url": "https://client.com/hooks", "events": ["order.created", "payment.completed"] }. Delivery challenges: the client endpoint may be down — use an at-least-once delivery strategy with exponential backoff retries (immediate, then 5m, 30m, 2h, 24h). Include a webhook signature header (HMAC-SHA256 of the payload using a shared secret) so clients can verify authenticity. Clients should respond quickly with 200 OK and process asynchronously — a timeout on the response triggers a retry. Stripe, GitHub, and Twilio all follow this pattern.
Previous
What is an API gateway and what responsibilities does it handle?
Next
What is an idempotency key for POST requests?
More REST API Design Questions
View all →- Intermediate What is HATEOAS and how is it implemented?
- Intermediate What are the main API versioning strategies in REST and what are their tradeoffs?
- Intermediate What are the pagination strategies in REST APIs?
- Intermediate What is rate limiting and how is it communicated in REST APIs?
- Intermediate How does HTTP caching work in REST APIs with ETag and Cache-Control?