Webhook Design

Delivery

• Send HTTP POST to the registered URL
• Include a JSON body with event type, id, timestamp, and data
• Use idempotency keys to handle duplicate deliveries
• Retry with exponential backoff (3-5 attempts, 1min/5min/15min/1h)
• Dead-letter queue after max retries

Security

• Sign every payload with HMAC-SHA256 using a shared secret
• Include signature in the header: X-Signature: sha256=<hex>
• Provide a secret that consumers can use to verify
• Allow consumers to verify the signature before processing

Payload Format

{
  "event_id": "evt_abc123",
  "event_type": "order.created",
  "created_at": "2026-01-01T00:00:00Z",
  "data": {
    "order_id": "ord_456",
    "amount": 2999,
    "currency": "USD"
  }
}

Consumer Expectations

• Webhook endpoints should respond quickly (<5s) — process async
• Respond with 2xx to acknowledge receipt
• Respond with 4xx/5xx to trigger a retry
• Be idempotent — processing the same webhook twice is safe
• Log all received webhooks for debugging