Designing outgoing webhooks that receivers can trust

Goal

Notify external systems of events reliably and verifiably, without becoming an attack vector for either side.

Prerequisites

A per-receiver shared secret exchanged out of band, and a durable queue of pending deliveries.

Steps

1. Give every event a unique id and a type; include a timestamp and a minimal payload with an address to fetch the full object.
2. Sign the exact bytes of the body together with the timestamp using HMAC-SHA256 with the receiver's secret; send the signature and timestamp in headers.
3. Receivers verify the signature with a constant-time comparison, reject old timestamps (replay window), and deduplicate by event id.
4. Deliver at least once: retry with exponential backoff and jitter on network errors and 5xx, stop on 4xx other than 429, cap attempts, and expose delivery status.
5. Never place secrets in the webhook URL; validate receiver URLs (https, no private addresses) to prevent server-side request forgery.
6. Rotate secrets with an overlap period during which both are accepted.

Expected result

Receivers can prove origin and integrity, tolerate duplicates, and recover from downtime; senders do not hang on slow receivers.

Limits and test basis

Ordering is not guaranteed across retries; receivers order by event timestamps or sequence numbers. Large payloads should not be pushed; link to them. Guidance follows common practice and the cited sources.