Developer platformAdministrators
Webhook verification, retries and deduplication
Receive customer-service events with HMAC verification and at-least-once handling.
Last reviewed: 2026-07-21
Before you start
- A public HTTPS receiver on Max or Enterprise
- A receiver that stores processed event IDs
Steps
Register and verify
Choose only required events. Compute HMAC-SHA256 over timestamp + "." + exact raw body, compare X-AOS-Signature in constant time, and reject stale timestamps. Private, loopback, link-local, credential-bearing and redirect targets are rejected.
Expected result: Only authentic requests reach processing.
Acknowledge, deduplicate and rotate
Store X-AOS-Event-Id and return 2xx quickly. Network errors, 408, 425, 429 and 5xx retry; other 4xx are terminal. Delivery is at least once. Secret rotation has a 24-hour dual-signature overlap.
Expected result: Retries and rotation do not create duplicate work.