Webhook System Specification Template

At-least-once delivery. This means consumers may receive the same event more than once (due to retries after ambiguous failures) and must handle deduplication using the event `id`. Exactly-once delivery is not achievable in distributed systems without requiring consumers to implement idempotency, which they should do regardless. Document this guarantee clearly in your webhook docs.

Store processed event IDs and check before processing. When a consumer receives an event, look up the `id` in a persistent store. If it has been seen before, return 200 without reprocessing. If not, process the event and store the ID. This idempotency check is the consumer's responsibility. Your docs should include code samples for this pattern in every supported language.

Include the full resource state at the time of the event. This eliminates the need for consumers to make a follow-up API call to fetch the current state, which reduces their API usage and removes a race condition (the resource may have changed between the event and the follow-up call). The tradeoff is larger payloads, but for most resources under 10KB this is acceptable.

Use the retry schedule with exponential backoff. If the endpoint recovers within the retry window (~34 hours in the example above), all queued events will be delivered in order. If it does not recover, mark events as failed, disable the endpoint, notify the admin, and provide a manual retry mechanism in the dashboard. The [SLA/SLO/SLI framework](/glossary/sla-slo-sli) can help you define the delivery guarantees you commit to.

Add a new event type when at least 3 consumers have requested it or when a new feature creates a state change that external systems need to react to in real time. Before adding the event, check whether an existing event already covers the use case (e.g., `order.updated` may be sufficient without a separate `order.address_changed` event). Keep the event catalog focused. The [API-first design](/glossary/api-first-design) principle applies: design events for consumers, not for your internal architecture. ---