Developer platform

Webhook verification, retries and deduplication

Configure an event receiver, verify authentic events, and recover from queued, retried or expired deliveries.

Who uses it: Administrators
Content updated: 2026-09-09

Before you start

A public HTTPS receiver using your own deployment domain or receiver domain
Enabled runtime switches; pooled deployments additionally need Max or Enterprise entitlement
The integration.manage permission for the action: view to read, edit to create/edit/test/retry/rotate, or delete to delete
Durable storage for event IDs and a receiver-configured timestamp tolerance

Steps

Create an event receiver

Open your own deployment domain at /app/int/docs?section=webhooks&lang=en or /app/int/docs?section=webhooks&lang=zh, then open Developer center → Webhook. Enter a name and public HTTPS URL, select only the needed events, and create the receiver. The real catalog is customer.created, customer.updated, conversation.created, conversation.assigned, conversation.status_changed, message.created and message.delivery_updated.

Expected result: The receiver subscribes to only selected events for the current tenant.

Save the secret and verify raw bytes

Save the Secret when it is shown once. Before JSON parsing, compute HMAC SHA256 over timestamp + "." + the exact raw request bytes. Compare only X-AOS-Signature in constant time, validate timestamp age against your receiver tolerance, then durably deduplicate by X-AOS-Event-Id. The sender rejects unsafe endpoint targets during setup.

Expected result: Signature and timestamp checks reject invalid requests; durable deduplication in your receiver prevents duplicate processing.

Test and read delivery history

Use Send test after creation or an endpoint edit. The test is type webhook.test with data {test:true}, and is sent only to the selected endpoint. HTTP 202 means queued; an actual 2xx in delivery history means the receiver succeeded. After durable event acceptance, return 2xx quickly and deduplicate by event ID.

Expected result: You can distinguish queue acceptance from receiver success and avoid duplicate work.

Handle retry and manual recovery

Network errors, 408, 425, 429 and 5xx retry automatically; other 4xx stop. There are seven total attempts. Manual retry keeps the event ID and is allowed only when the delivery failed, attempts have been made fewer than seven times, the payload is valid and the receiver is enabled. Exhausted, cancelled or expired deliveries cannot be retried. An older retry may arrive after newer events.

Expected result: The receiver uses event ID and event ordering rules to make retries safe.

Rotate or disable deliberately

During secret rotation, accept signatures made with the old and new secret for 24 hours, then remove the old receiver secret. Disable, delete or downgrade cancels the backlog; re-enabling does not replay events from the disabled period. Payloads are retained for seven days and delivery records for 30 days.

Expected result: Rotation and lifecycle changes have predictable replay and retention behavior.