Sign every webhook and give each event a stable ID

Sign each webhook over its body and a timestamp, give every event an ID that stays the same across retries, and document that delivery is retried and unordered, so the receiving agent can reject forgeries and act on each event once.

Why

AX-SYS-17 says to send webhooks. Once you do, receivers act on them: a charge.refunded event might close a case or email a customer. A webhook URL is reachable by anyone who finds it, so without a signature a forged event looks like a real one, and a captured real event can be replayed. GitHub tells receivers to validate the signature before processing a delivery any further, so they know it came from GitHub and was not tampered with. Stripe puts a timestamp inside its Stripe-Signature header, which lets a receiver reject a correctly signed payload that is too old. Delivery is the other half. Stripe retries failed deliveries for up to three days with exponential backoff in live mode, warns that an endpoint might receive the same event more than once, tells receivers to log processed event IDs and skip repeats, and does not guarantee order. CloudEvents makes the ID part of the format: producers must keep source plus id unique per distinct event, a resend may carry the same id, and consumers may treat a repeated pair as a duplicate. Without a stable ID, a retried charge.refunded looks like a second refund.

Do

Sign the raw body plus a timestamp, keep the same event ID on every delivery attempt, and publish your retry schedule and the fact that order is not guaranteed.

Don't

Send unsigned webhooks, mint a new ID on each retry, or imply that events arrive exactly once and in order.

Artifact

POST /hooks/acme HTTP/1.1
Content-Type: application/cloudevents+json
Acme-Signature: t=1791036000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e7...
Acme-Delivery-Attempt: 2

{
  "specversion": "1.0",
  "id": "evt_4410",
  "source": "https://api.acme.com/charges",
  "type": "com.acme.charge.refunded",
  "time": "2026-10-03T14:00:00Z",
  "data": { "charge_id": "ch_123", "amount": 4900 }
}

The receiver checks the HMAC over the timestamp and raw body, rejects stale timestamps, and skips any id it has already processed; attempt 2 carries the same id as attempt 1.