Webhooks and event-driven APIs

Webhooks push domain events to subscriber URLs — payment settled, shipment dispatched. Consumers must treat delivery as **at-least-once**.

Sender responsibilities:

• **Sign payloads** (HMAC-SHA256 with timestamp, e.g. Stripe-style `Stripe-Signature`).
• **Retries** with exponential backoff on non-2xx; cap attempts; dead-letter queue.
• **Idempotency**: event id + dedup store on consumer; same event may arrive twice.
• **Ordering**: usually per-resource sequence, not global — document guarantees.

					POST https://merchant.example/webhooks/payments
Content-Type: application/json
X-Webhook-Id: evt_01H...
X-Webhook-Signature: t=1710000000,v1=abc123...

{"type":"payment.succeeded","data":{"paymentId":"pay_1"}}
				

Consumer responsibilities:

• Verify signature and timestamp skew window.
• Respond 2xx quickly; process async via queue.
• Return 4xx only for permanent rejection (bad signature); 5xx triggers retry.

On interviews: webhook vs polling, signature verification steps, and idempotent handlers.

Common pitfalls: no signature verification, heavy work in request thread, assuming exactly-once delivery, and silent subscription endpoint changes without versioning.

The trade-off is realtime integration versus delivery complexity — invest in replay tools and event catalogs.

Checklist:

• Signed payloads with timestamp.
• Documented retry and DLQ policy.
• Consumer dedup by event id.
• Fast 2xx + async processing.