Version 1 / Guides / Webhooks

Receive, persist, then acknowledge

Webhook delivery is at least once. A receiver must make duplicates harmless and persist the delivery identity before returning a successful status.

Receiver contract

1. 1

   Read the raw request bytes

   Do not parse and reserialize before signature verification.

2. 2

   Verify the registered signature contract

   Reject invalid credentials, signatures and timestamps without performing business work.

3. 3

   Persist the delivery identity durably

   Deduplicate by the contract identifier before acknowledging. An in-memory set is not sufficient.

4. 4

   Return success only after the durable write

   If persistence fails, return failure so delivery can retry. Never return success and hope to persist later.

5. 5

   Treat order as explicit, not accidental

   Use record and delivery sequence fields defined by the published schema; do not infer order from arrival time.