Webhook verification, retries and deduplication
Receive customer-service events with HMAC verification and at-least-once handling.
- Who uses it
- Administrators
- Guide depth
- 2 steps
- Content reviewed
- 2026-07-22
What this helps you achieve
The practical result of following this guide, with the current product boundaries kept visible.
Register and verify
Only authentic requests reach processing.
Acknowledge, deduplicate and rotate
Retries and rotation do not create duplicate work.
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.