Skip to main content

Webhooks

Webhooks notify your system when important events happen in CashXChain.

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": "evt_7F2...",
  "type": "payment.completed",
  "created_at": "2026-06-01T09:00:42Z",
  "environment": "sandbox",
  "resource_type": "payment",
  "resource_id": "pay_6pD3...",
  "data": {
    "id": "pay_6pD3...",
    "status": "completed"
  }
}

Signature headers​

CashXChain signs webhook payloads. Example headers:

X-CXC-Event-Id: evt_7F2...
X-CXC-Timestamp: 1780304442
X-CXC-Signature: v1=...

Verify the signature before trusting the payload.

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.

Common event types​

  • account.verified
  • beneficiary.active
  • quote.expired
  • payment.created
  • payment.requires_action
  • payment.processing
  • payment.completed
  • payment.failed
  • payment.returned
  • balance.updated
  • statement.available

Testing​

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