Skip to main content

Webhooks API

Webhooks notify your system when important events happen in CashXChain.

Planned

Customer-managed webhook endpoints (registering your own URL via /v1/webhooks and receiving signed POSTs) are on the roadmap and not yet available in the sandbox API. Today, events are available as a server-sent event (SSE) stream from the dashboard session — see Event stream. The signed-POST contract below is the planned model.

Event stream (available today)​

GET /v1/notifications

A long-lived SSE stream of account, transfer/payment, and balance events for the authenticated session. This is a dashboard (session) endpoint and is not consumed with a developer API key.

Planned: signed webhook delivery​

Endpoint requirements​

Your endpoint must:

  • Use HTTPS.
  • Accept POST requests.
  • Return a 2xx response quickly.
  • Verify CashXChain signatures.
  • Handle duplicate events safely.
  • Process events asynchronously when possible.

Event format​

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "transfer.completed",
  "created_at": "2026-06-01T09:00:42Z",
  "environment": "sandbox",
  "resource_type": "transfer",
  "resource_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "completed"
  }
}

Signature headers​

The signing scheme is being finalized. Plan to verify a signature header (timestamp + HMAC) over the raw request body before trusting the payload; the exact header names will be published with the endpoint.

Delivery behavior​

If your endpoint does not return a 2xx response, delivery is retried with backoff. Events may be delivered more than once and may arrive out of order.

Idempotency​

Use the event ID to deduplicate processing. Your handler should be safe to run multiple times.

Planned event types​

Aligned to the transfer/payment lifecycle:

  • transfer.pending
  • transfer.executing
  • transfer.completed
  • transfer.failed
  • transfer.rolled_back
  • payment.sent
  • payment.completed
  • payment.failed

Testing​

Use sandbox to validate event handling — deduplication, retries, and reconciliation — against the event stream.