Webhooks & Event Delivery

A webhook inverts the integration: instead of a consumer polling you, you call them when something happens. It removes polling latency and wasted requests, and it hands you every problem of being an HTTP client to an endpoint you do not control.

Receivers must verify. Your endpoint is on the public internet and anyone can POST to it. Providers sign the payload — typically HMAC-SHA256 over the raw body with a shared secret — and you must verify that signature before parsing or acting. Two details matter: compute the HMAC over the exact raw bytes, because re-serialising the JSON changes the signature, and use a constant-time comparison.

Include a timestamp and reject old ones, or a captured request can be replayed indefinitely against you.

Delivery is at-least-once. Networks fail after your handler committed but before the response arrived, so every consumer will eventually see duplicates. Providers send an event id; receivers must be idempotent, either by recording processed ids or by making the operation naturally repeatable.

Ordering is not guaranteed. Retries and parallel delivery mean "updated" can arrive before "created". Include a sequence number or a version on the resource and ignore anything older than what you have already applied.

Respond fast, process later. Acknowledge with a 2xx as soon as the payload is verified and durably queued, then do the work asynchronously. Providers time out aggressively and treat slowness as failure, so processing inline earns you retries you did not need and a duplicate storm on a slow day.

Senders need discipline too: exponential backoff with jitter, a cap on attempts, a dead letter path, and somewhere the consumer can see and replay failures. And treat the destination URL as untrusted — a user-supplied webhook target pointed at an internal address is a classic SSRF.