Verify, Persist, and Respond Quickly
Verify the signature using the raw body, persist the event, and return a 2xx response within 10 seconds. Process business logic asynchronously when possible.Handle Duplicates
Events may be delivered more than once. Use the envelopeid to deduplicate deliveries:
Handle Out-of-Order Events
Events may arrive out of sequence. Compare the resource’supdated timestamp before replacing local state:
Retry Behavior
Connection errors, timeouts, and non-2xx responses are retried with exponential backoff. Delivery currently allows up to 12 attempts, beginning with a five-minute retry delay and capping the delay at six hours. Theattempt field and X-Webhook-Attempt header identify the current attempt.
Repeated delivery failures do not automatically delete or disable the webhook endpoint. Use the Delete Webhook Endpoint API when an endpoint should stop receiving events.
Local Testing
Because registered endpoints must use HTTPS, expose your local server through an HTTPS tunnel such as ngrok:https:// URL as a webhook endpoint in the sandbox environment.