Real-Time APIs · Webhooks
Designing Webhook Delivery (Sender Side)
Event types, payloads, subscriptions and delivery pipeline.
As a provider, let consumers subscribe endpoints to specific event types, send compact event payloads (id, type, created time, data — or thin events with a resource URL), deliver from a background pipeline (never inline in the request that caused the event), retry with exponential backoff for up to ~3 days, isolate slow endpoints, and give consumers a dashboard: delivery logs, response codes, manual resend, endpoint disabling. Follow the Standard Webhooks spec for headers and signatures.
Sender design choices
| Design choice | Option A | Option B |
|---|---|---|
| Payload | Fat event (full data) | Thin event (id + URL; consumer fetches) |
| Delivery | Per endpoint queue | Shared queue (risk: slow endpoints block) |
| Ordering | Not guaranteed (document it) | Per-resource ordering (complex) |
| Failure policy | Retries ~3 days, then disable + notify | Retry forever (bad) |
POST https://consumer.example.com/hooks/acme
webhook-id: msg_2Ki1Vh8l2QpNp9Yb
webhook-timestamp: 1791627600
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Content-Type: application/json
{"type": "invoice.paid", "timestamp": "2026-10-11T09:00:00Z",
"data": {"invoice_id": "inv_92", "amount": 4900, "currency": "EUR"}}
Common pitfalls
- Sending webhooks synchronously from the triggering request.
- One slow consumer delaying everyone.
- No delivery logs or resend tooling.
Key points
- Subscriptions by event type
- Async per-endpoint delivery with retries
- Logs, resend, Standard Webhooks
Further reading: Standard Webhooks
Practice questions
Why deliver webhooks from a background pipeline?
Answer
Consumer endpoints can be slow or down; inline delivery would slow or fail the original request and lose events on errors.
What's the trade-off of thin webhook payloads?
Answer
Consumers must call back to fetch data (extra requests, need API access), but always get the latest state and the payload leaks less data.
Open in the app to mark lessons complete, take notes and track your progress.