Webhooks
Retries & idempotency
Webhook deliveries are at-least-once. Verify, deduplicate, acknowledge quickly, and process side effects asynchronously.
Delivery guarantees
- At-least-once delivery — the same event may arrive more than once.
- Return any 2xx response to mark a delivery successful.
- Non-2xx responses trigger automatic retry with exponential backoff.
- Ordering is not guaranteed across different event types or resources.
Recommended handler pattern
- Verify the HMAC signature on the raw body.
- Parse JSON and read event
id(orx-xpend-delivery-id). - Check durable storage — if already processed, return 2xx immediately.
- Enqueue side effects (fulfillment, ledger updates) to a background job.
- Return 2xx before slow work finishes.
Make downstream operations idempotent using your own business keys (e.g. payment_intent_id, order_id in metadata) so duplicate events cannot double-fulfill.
Ordering
Do not assume
deposit_confirmed always arrives before completed relative to other payment intents. Within one payment intent, treat completed as the fulfillment signal. See Events for when each type fires.Related
- API idempotency guide — webhook-specific notes.
- Webhooks overview — endpoint registration.