Webhook

Why push beats polling#

Polling a collection endpoint on a timer is slower, consumes rate limit, and scales badly — most requests return nothing. A webhook delivers the event when it happens, which means an approval in the document system can advance a case in another system within seconds.

Idempotency is not optional#

Delivery is at-least-once, not exactly-once. Networks fail, receivers time out, and the sender retries — so the same event will arrive twice, and a handler that processes it twice will eventually cause a visible problem. Use the event identifier to detect a repeat.

This is the single most common webhook implementation mistake.

Payload signing#

Each payload should carry a signature computed with a shared secret, so the receiver can verify it came from the expected sender and has not been replayed. Without verification, a webhook endpoint is an unauthenticated write path into your system that anyone who learns the URL can use.

Respond fast, process later#

Acknowledge receipt immediately and do the work asynchronously. A handler that performs a slow operation before responding causes timeouts, which causes retries, which causes duplicate processing — the failure mode compounds.

Ordering#

Event order is not guaranteed across types. Do not infer sequence from arrival order; use timestamps or version numbers in the payload.