← All templates

Signed delivery, backoff, idempotency, dead-letter queue.

Spec — Webhook with retries

Status: draft · Created: 2026-10-12

1. Context and goal

Subscribers receive events at their URL reliably, once in effect, and can verify that each delivery is genuine.

2. Functional requirements (EARS)

  • FR-1: WHEN an event happens, THE SYSTEM SHALL deliver it to every active subscription for its type within 5 seconds.
  • FR-2: THE SYSTEM SHALL sign each delivery with HMAC-SHA256 of the timestamp and the body, in a header.
  • FR-3: IF a delivery fails or times out after 10 seconds, THEN THE SYSTEM SHALL retry with exponential backoff for up to 24 hours.
  • FR-4: THE SYSTEM SHALL send the same event id on every retry so subscribers can ignore duplicates.
  • FR-5: IF every retry fails, THEN THE SYSTEM SHALL move the event to a dead-letter queue and notify the owner of the subscription.
  • FR-6: WHEN an owner replays a dead-letter event, THE SYSTEM SHALL deliver it again with the same id.
  • FR-7: WHILE a subscription has failed for 3 days, THE SYSTEM SHALL disable it and tell its owner.
  • FR-8: THE SYSTEM SHALL keep a delivery log with status, attempts and response codes for 30 days.

3. Out of scope

  • Ordering guarantees between different events.