Webhooks

Webhooks notify your own HTTPS callback about your account’s events, cryptographically signed.

Create a subscription

curl -X POST https://api.qbank.cl/platform/v1/webhooks/subscriptions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "payout_status_changed",
    "callback_url": "https://api.myapp.com/webhooks/cbpay",
    "secret": "a-secret-of-at-least-16-chars"
  }'

event_type: one of the events below, or * for all.
callback_url: HTTPS required; localhost and private IPs are rejected — for local development use an HTTPS tunnel.
secret: at least 16 characters; used to sign every delivery. Stored encrypted and cannot be retrieved.

The subscription receives your account’s events. You can list active subscriptions at any time:

curl https://api.qbank.cl/platform/v1/webhooks/subscriptions \
  -H "Authorization: Bearer <token>"

{
  "page": 1,
  "page_size": 50,
  "subscriptions": [
    {
      "id": "5f3a…",
      "event_type": "payout_status_changed",
      "callback_url": "https://api.myapp.com/webhooks/cbpay",
      "status": "active",
      "created_at": "2026-07-01T12:00:00Z"
    }
  ]
}

Events

Event	When it fires
`payin_credited`	A fiat collection was received and credited
`payin_expired`	An active collection (QR / checkout) expired or failed without receiving the payment
`payout_status_changed`	A payout changed state
`transfer_received`	The account received an internal transfer
`crypto_deposit_credited`	An on-chain deposit was confirmed and credited
`crypto_deposit_held`	An incoming deposit was held due to sender risk (screening)
`crypto_deposit_alert`	A deposit was credited but the sender shows high risk (informational)
`crypto_withdrawal_status_changed`	An on-chain withdrawal changed state
`banking_customer_status_changed`	Your banking profile verification changed
`banking_operation_status_changed`	A bank payment changed state
`card_transaction`	A card purchase was authorized, annulled or adjusted
`card_status_changed`	A card changed state (including automatic freezes)
`kyc_verification_status_changed` / `kyb_verification_status_changed`	An identity verification changed state (including your own onboarding, with `self_onboarding: true`)
`kyc_link_completed` / `kyb_link_completed`	A hosted verification link was completed
`kyc_document_validated` / `kyb_document_validated`	OCR finished for a document uploaded through the API
`kyc_liveness_completed`	A liveness check was completed from a liveness link
`aml_screening_updated`	AML screening updates (result, cases, risk, reviewed transaction)
`wallet_deposit_received`	An on-chain deposit arrived at a segregated wallet (does not touch the ledger)
`wallet_send_status_changed`	A send from a segregated wallet changed status
`wallet_key_exported`	A segregated wallet’s private key was exported (security alert)
`wallet_external_movement`	On-chain movement of a segregated wallet that did not go through the platform (expected under `client` custody)
`wallet_key_compromise_suspected`	Critical alarm: external outflow from a `cbpay`-custody wallet — possible key compromise

Payload of each event

{
  "payin_id": "9c2a…",
  "account_id": "ae8c…",
  "country": "BO",
  "currency": "BOB",
  "local_amount": "700.00",
  "fx_rate": "6.91",
  "usdt_credited": "100.302460",
  "fee": "1.000000"
}

{
  "payin_id": "567d…",
  "account_id": "ae8c…",
  "status": "expired",
  "country": "BO",
  "currency": "BOB",
  "local_amount": "60.99",
  "reference": "CBK7Q2M4XZ9P"
}

{
  "payout_id": "0d4f…",
  "account_id": "ae8c…",
  "country": "MX",
  "currency": "MXN",
  "local_amount": "1500.00",
  "usdt_amount": "85.714286",
  "total_debit": "86.014286",
  "status": "completed",
  "status_code": ""
}

{
  "transfer_id": "77b1…",
  "from_account_id": "389d…",
  "to_account_id": "ae8c…",
  "asset": "USDT",
  "amount": "25.000000",
  "description": "Expense split",
  "created_at": "2026-07-06T20:10:00Z"
}

{
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "tx_id": "b1946ac9…",
  "amount": "499.000000",
  "fee": "1.000000"
}

{
  "account_id": "ae8c…",
  "hold_id": "c1d2e3f4…",
  "chain": "tron",
  "asset": "usdt",
  "tx_id": "8a5b3c…",
  "risk": "Severe",
  "status": "held"
}

{
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "usdt",
  "tx_id": "9c6d4e…",
  "risk": "High",
  "status": "credited"
}

{
  "withdrawal_id": "5e8c…",
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "tx_id": "7d3f01aa…",
  "status": "completed",
  "amount": "100.000000"
}

{
  "account_id": "ae8c…",
  "customer_id": "9f2b…",
  "kyc_status": "approved"
}

{
  "account_id": "ae8c…",
  "customer_id": "9f2b…",
  "operation_id": "7e8a…",
  "type": "withdraw",
  "status": "completed"
}

{
  "account_id": "ae8c…",
  "card_id": "3c2b…",
  "transaction_id": "5e4d…",
  "status": "authorized",
  "amount_usdt": "16.170000",
  "merchant": "AMZN Mktp"
}

{
  "account_id": "ae8c…",
  "card_id": "3c2b…",
  "status": "frozen",
  "reason": "monthly_fee_unpaid"
}

{
  "account_id": "ae8c…",
  "kind": "kyc",
  "event": "approved",
  "submission_id": "c3d4…",
  "external_customer_id": "cust_789",
  "status": "approved",
  "risk_band": "low",
  "decision": "approved"
}

{
  "account_id": "ae8c…",
  "kind": "kyb",
  "event": "link_completed",
  "link_id": "b2c3…",
  "submission_id": "d4e5…",
  "external_customer_id": "cust_456",
  "status": "completed"
}

{
  "account_id": "ae8c…",
  "kind": "kyc",
  "submission_id": "c3d4…",
  "external_customer_id": "cust_789",
  "category": "identity",
  "outcome": "MATCH",
  "score": 0.97,
  "summary": "Document matches the submitted identity"
}

{
  "account_id": "ae8c…",
  "kind": "kyc",
  "submission_id": "c3d4…",
  "external_customer_id": "cust_789",
  "outcome": "PASS",
  "passed": true
}

{
  "account_id": "ae8c…",
  "screening_event": "compliance_risk_changed",
  "customer_id": "cus_8f2e…",
  "data": { "risk_level": "high" }
}

{
  "wallet_id": "b7e3…",
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "tx_id": "b1946ac9…",
  "amount_raw": "125000000",
  "from_address": "TDonor…"
}

{
  "send_id": "9c8b…",
  "wallet_id": "b7e3…",
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "tx_id": "b1946ac9…",
  "status": "completed",
  "amount_raw": "25500000"
}

{
  "wallet_id": "b7e3…",
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "address": "TRmSZRaMAqLEevAdGwo3R43bRBXamWR5bd"
}

{
  "wallet_id": "b7e3…",
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "direction": "out",
  "tx_id": "9a3c1e5f…",
  "amount_raw": "25000000",
  "custody": "client"
}

{
  "wallet_id": "b7e3…",
  "account_id": "ae8c…",
  "chain": "tron",
  "asset": "USDT",
  "direction": "out",
  "tx_id": "9a3c1e5f…",
  "amount_raw": "25000000",
  "custody": "cbpay"
}

In payout_status_changed and crypto_withdrawal_status_changed, status can be completed or failed (with failed, the debit has already been refunded by the time you receive the event).

Delivery format

Every delivery is a JSON POST with these headers:

Header	Content
`X-Webhook-Event`	Event type
`X-Webhook-Event-ID`	Unique event ID
`X-Webhook-Delivery-ID`	This delivery’s ID (changes across retries)
`X-Webhook-Timestamp`	Unix timestamp (seconds, UTC)
`X-Webhook-Signature`	HMAC signature (see below)

Verify the signature

X-Webhook-Signature = hex( HMAC-SHA256( secret, timestamp + "." + body ) )

const crypto = require("crypto");

function verifyWebhook(req, secret) {
  const ts = req.headers["x-webhook-timestamp"];
  const sig = req.headers["x-webhook-signature"];
  const expected = crypto
    .createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

import hashlib, hmac

def verify_webhook(headers, raw_body: bytes, secret: str) -> bool:
    ts = headers["X-Webhook-Timestamp"]
    sig = headers["X-Webhook-Signature"]
    expected = hmac.new(
        secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig, expected)

Compute the HMAC over the raw body (bytes as received), not over re-serialized JSON. Reject old timestamps (> 5 minutes) to prevent replay.

Retries and idempotency

Your endpoint must respond 2xx within the timeout; anything else is retried.
Up to 5 attempts with incremental backoff:

Attempt	1	2	3	4	5
Approx. wait	immediate	~5s	~20s	~45s	~80s

Use X-Webhook-Event-ID to deduplicate: the same event can arrive more than once (at-least-once delivery).
If all 5 attempts fail the event is not resent — recover the state with the resource’s GET (which is why no flow should depend ONLY on the webhook).

Best practices

Respond 200 immediately and process in the background.
Log the X-Webhook-Delivery-ID for traceability.
Don’t rely solely on webhooks for critical states: you can always query the object by API (GET /v1/payouts/{id}, etc.).

Getting Started

Concepts

Integration flows

Products

Integration

Resources

Create a subscription

Events

Payload of each event

Delivery format

Verify the signature

Retries and idempotency

Best practices

​Create a subscription

​Events

​Payload of each event

​Delivery format

​Verify the signature

​Retries and idempotency

​Best practices

Create a subscription

Events

Payload of each event

Delivery format

Verify the signature

Retries and idempotency

Best practices