Reviewedv1Integrations

Receiving webhooks safely

Verify the signature before parsing, acknowledge quickly, then process through a replay-safe inbox.

Last reviewed: July 16, 2026
Audience: backend · integration
Contract state: Reviewed

Verify first

Read the raw body, verify timestamp, signature, and event id, then parse. Mutating the body before verification breaks the canonical signature.

raw_body -> timestamp window -> signature -> event_id dedupe -> parse -> enqueue

Delivery semantics

Treat webhook delivery as at-least-once. An event may arrive more than once or out of order, so persist event_id in an inbox with a unique constraint.

Return 2xx after safe persistence, not after all business work completes.
Use 4xx only for permanent rejection and 5xx for transient failure.
Never assume order; compare version or occurred_at as defined by contract.

Secret rotation

Support a short overlap accepting current and previous secrets, observe use of the old secret, then revoke it when rotation completes.