Webhooks overview

How it works

Xpend POSTs JSON to your HTTPS endpoint when something changes — a deposit confirms, funds settle, or a payout finishes. Deliveries are at-least-once and HMAC-signed. Your handler should verify the signature, deduplicate by event ID, return 2xx, and do the real work asynchronously.

1. Register an endpoint and store the one-time signing_secret.
2. Verify signatures on every request before parsing the body.
3. Handle events for the types you subscribed to.
4. Acknowledge quickly and stay idempotent — duplicates and retries are normal.

1. Register an endpoint

{
  "url": "https://example.com/webhooks/xpend",
  "event_types": [
    "payment_intent.deposit_confirmed",
    "payment_intent.completed",
    "payout.completed",
    "payout.failed"
  ]
}

Omit event_types to subscribe to all supported types. List them with GET /v1/webhooks/endpoints/supported-event-types.

2. What you receive

Each delivery is a POST with JSON body and three headers: x-xpend-signature, x-xpend-timestamp, and x-xpend-delivery-id. The body always uses this envelope — event-specific fields are under data.

{
  "id": "evt_01HXYZ...",
  "type": "payment_intent.completed",
  "api_version": "2026-05-10",
  "created_at": "2026-03-19T16:32:11.000Z",
  "merchant_id": "merchant_xyz",
  "environment": "test",
  "data": { }
}

Full payload examples for each event type are on the Events page. Signature verification steps are on Signature verification.

3. Manage endpoints

Endpoint management and delivery history APIs are listed in the Webhooks API reference.

Read next

• Events — when each type fires and example payloads.
• Signature verification — HMAC check with Node.js example.
• Retries & idempotency — duplicates, ordering, and fast acknowledgements.