Skip to main content

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 envelope id to deduplicate deliveries:

Handle Out-of-Order Events

Events may arrive out of sequence. Compare the resource’s updated 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. The attempt 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:
Register the generated https:// URL as a webhook endpoint in the sandbox environment.