Webhook Delivery Service  ·  View 13 of 20  ·  Runtime

Signing, Rotation and Verification

From key generation to the consumer's comparison, including the seven-day overlap.

Editable source SVG draw.io All views
Subscription Service AWS KMS Secret Store Delivery Worker Consumer Verifier Consumer Handler 1. generate data key 2. plaintext + wrapped 3. persist wrapped only 4. show once, never again 5. read active secrets 6. decrypt, cached 5 min 7. HMAC over ts + raw body 8. POST + signature headers 9. recompute over raw bytes 10. reject if ts outside window 11. dispatch event 12. 200 OK 13. rotate: second secret active 14. both signatures, 7 d overlap 15. 401 if neither verifies Signing, Rotation and Consumer Verification A 401 from the verifier is a permanent outcome: the platform stops retrying and tells the endpoint's owner. v 1.0 · owner Integration Platform Architecture · date 2026-09

Decisions

  • HMAC-SHA-256 over timestamp plus the exact raw request body, under a KMS-wrapped per-endpoint secret. Asymmetric signatures are the better answer to a platform-side compromise and are deferred to Phase 3 (ADR-06).
  • Two active secrets, both signatures sent, seven-day overlap. Rotation is a data property the consumer migrates through at their own pace, not a coordinated cut-over (ADR-07).
  • The secret is displayed exactly once and never again. A secret the console can show is a secret an account takeover can read.
  • The platform reads at most a bounded prefix of the response and never parses it for control information. The response body is untrusted input from an untrusted party.

The consumer's half

  • Recompute over raw bytes, not over a re-serialised object — the single most common cause of a mismatch, and the reason the canonical string is published rather than described.
  • Reject if the timestamp is outside the acceptance window; the timestamp is in the signed material specifically so a captured request cannot be replayed indefinitely.
  • A 401 is classified permanent: the platform stops retrying and tells the endpoint's owner rather than hammering a consumer that is correctly refusing it.

Assumptions

  • KMS decrypt cached 5 minutes per worker. Secret rotation effective within 60 s p99 — these two numbers are in tension, and the cache TTL is the one that gives.
  • A recommended acceptance window of 5 minutes is published rather than enforced; the platform cannot enforce a consumer's clock.
◀  Retry, Circuit Breaking and Dead Letter All views Replay and Recovery  ▶
Solution Architecture v1.0 · Amazon Web Services · Integration Platform Architecture · 2026-09 · 20 views · 16 architecture decision records13-signing-and-verification