Webhooks

Webhooks notify your system when important events happen in CashXChain.

Planned

Customer-managed webhook endpoints are on the roadmap and not yet available. Today, events are exposed as a server-sent event (SSE) stream from the dashboard session (GET /v1/notifications). The signed-POST model below is the planned contract — see the Webhooks API.

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

Signed delivery will include a timestamp and an HMAC signature over the raw request body, which you must verify before trusting the payload. The exact header names are being finalized and will be published with the endpoint.

Delivery behavior

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

Idempotency

Use the event ID to deduplicate processing. Your webhook 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
• balance.updated

Testing

Use sandbox to trigger test events and validate signature verification, retries, duplicate handling, and reconciliation workflows.