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:
updated is always UTC with a Z suffix. Parse it; do not compare the strings: a change of precision or offset would silently break a lexical comparison.

Retry Behavior

Connection errors, timeouts, and non-2xx responses are retried. Each attempt has a 10-second HTTP timeout, and the backoff triples each time, starting at five minutes and capped at six hours: Delivery stops after 12 attempts, which spans roughly 45 hours from the first attempt. The attempt field and the X-Webhook-Attempt header identify the current attempt. Once those 12 attempts are exhausted the notification is marked failed and is not sent again. There is no replay or redelivery endpoint, so a delivery you never accepted cannot be recovered from the API: reconcile with List Payouts, List Payins and the other list endpoints to find what you missed. 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. There is no ping or test-delivery endpoint. To put a real signed delivery through your handler, call Simulate Payin in sandbox: it credits a balance and raises a genuine payin.received event, signed and retried exactly as a production delivery is.