Webhook Events

This page lists every webhook event Caliza can send, with payload examples and data object shapes. For setup and configuration, see Webhooks.

Every webhook shares the same envelope structure. The data field varies by event type — each section below documents its shape.

Transaction events

Transaction events use a transaction object as the data field. This is the same shape across TRANSACTION_COMPLETED, TRANSACTION_FAILED, TRANSACTION_EXPIRED, TRANSACTION_UNDER_REVIEW, TRANSACTION_REFUNDED, CRYPTO_DEPOSIT_RECEIVED, and PAYMENT_IN_COMPLETED.

Transaction data object

📘

Fields are omitted from the payload when their value is null.

TRANSACTION_COMPLETED

Sent when a transaction has been fully executed and the funds have been delivered to the final destination. This is the most common webhook.

{
  "operation": "TRANSACTION_COMPLETED",
  "resourceId": "632a208b806bd70097197367",
  "createdAt": "2024-09-20T17:20:28.935890",
  "integratorId": "6306548828912548710e667c",
  "beneficiaryId": "6306556b28912548710e667e",
  "message": null,
  "success": true,
  "data": {
    "id": "632a208b806bd70097197367",
    "simulationId": "632a2088806bd70097197366",
    "integratorId": "6306548828912548710e667c",
    "beneficiaryId": "6306556b28912548710e667e",
    "from": { "currencyCode": "BRL", "value": 500.00 },
    "to": { "currencyCode": "USD", "value": 97.52 },
    "status": "SUCCEEDED",
    "exchangeRate": 4.98,
    "totalFees": { "currencyCode": "BRL", "value": 14.80 },
    "flowOfFundsId": "55b778b2-1d8e-48fb-8229-0386d0f33fe0"
  }
}

TRANSACTION_FAILED

Sent when a transaction cannot be completed due to an error at any step in the payment flow, or when a transaction is rejected by compliance screening.

{
  "operation": "TRANSACTION_FAILED",
  "resourceId": "632a208b806bd70097197367",
  "createdAt": "2024-08-02T15:51:49.119000",
  "integratorId": "6306548828912548710e665a",
  "beneficiaryId": "6306548828912548710e667a",
  "success": false,
  "message": "Something went wrong",
  "data": {
    "id": "632a208b806bd70097197367",
    "simulationId": "632a2088806bd70097197366",
    "integratorId": "6306548828912548710e665a",
    "beneficiaryId": "6306548828912548710e667a",
    "from": { "currencyCode": "USD", "value": 100.00 },
    "to": { "currencyCode": "BRL", "value": 0 },
    "status": "FAILED",
    "rejectionReason": "Compliance review"
  }
}

When you receive this event, inform your end user that the transaction did not go through. Depending on the failure reason, a retry with a new simulation may be possible.

TRANSACTION_EXPIRED

Sent when a transaction exceeds its time-to-live without completing. This typically occurs when the required deposit is not received within the allowed window. Uses the same transaction data object with status: "EXPIRED".

TRANSACTION_UNDER_REVIEW

Sent when a transaction has been flagged for manual review. This can occur when an ACH payment is placed on hold by the banking partner. Inform your end user that the transaction may take additional time to process.

TRANSACTION_REFUNDED

Sent when a previously completed transaction has been refunded. The resourceId refers to the original transaction. Uses the same transaction data object.

SWIFT tracking events

TRANSACTION_UETR

Sent when SWIFT wire tracking information is attached to a transaction. The data object has a different shape from transaction events:

{
  "operation": "TRANSACTION_UETR",
  "resourceId": "632a208b806bd70097197367",
  "createdAt": "2024-09-20T18:30:00.000000",
  "integratorId": "6306548828912548710e667c",
  "beneficiaryId": "6306556b28912548710e667e",
  "success": true,
  "data": {
    "transactionId": "632a208b806bd70097197367",
    "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d",
    "pacs": "PACS008REF123",
    "imad": "20240920MMQFMP0F000001",
    "omad": "20240920MMQFMP0F000002"
  }
}

Deposit received events

These webhooks are sent when Caliza receives the initial funding for a transaction. They use the same transaction data object described above.

CRYPTO_DEPOSIT_RECEIVED

Sent when a cryptocurrency deposit (USDC or USDT) is confirmed on-chain. The data object will include depositTransactionHash with the on-chain hash.

Applies to: USDC or USDT funded corridors (to USD, COP, HKD, SGD, and others)

PAYMENT_IN_COMPLETED

Sent when an inbound fiat payment (ACH, WIRE, SWIFT, or RTP) is received and credited to your account.

Applies to: USD deposits via ACH, WIRE, SWIFT, and RTP

Beneficiary events

Beneficiary events use a beneficiary object as the data field.

Beneficiary data object

BENEFICIARY_APPROVED

Sent when a beneficiary has been fully verified and approved. The beneficiary is now ready to receive payments.

{
  "operation": "BENEFICIARY_APPROVED",
  "resourceId": "6306556b28912548710e667e",
  "createdAt": "2024-09-20T12:00:00.000000",
  "integratorId": "6306548828912548710e667c",
  "beneficiaryId": "6306556b28912548710e667e",
  "success": true,
  "data": {
    "id": "6306556b28912548710e667e",
    "integratorId": "6306548828912548710e667c",
    "integratorBeneficiaryId": "ext-ben-001",
    "type": "PERSON",
    "active": true,
    "status": "APPROVED",
    "approvedDate": "2024-09-20T12:00:00.000000Z",
    "createdDate": "2024-09-19T10:30:00.000000Z"
  }
}

BENEFICIARY_FAILED

Sent when beneficiary creation or verification has failed. Check the message field for details on the failure reason.

Pay-in account events

PAY_IN_ACCOUNT_CREATED

Sent when a virtual pay-in account has been created with deposit instructions. The data object contains the wiring information your end user needs to fund their account.

Pay-in account data object

{
  "operation": "PAY_IN_ACCOUNT_CREATED",
  "resourceId": "6306556b28912548710e667e",
  "createdAt": "2024-09-20T14:00:00.000000",
  "integratorId": "6306548828912548710e667c",
  "beneficiaryId": "6306556b28912548710e667e",
  "success": true,
  "data": {
    "accountNumber": "123456789012",
    "routingNumber": "021000021",
    "receiverName": "Caliza Inc.",
    "receiverBankName": "Example Bank",
    "referenceNumber": "REF-2024-001"
  }
}

Sweep payout events

These webhooks track the lifecycle of sweep payouts. They use the same transaction data object as transaction events, with the addition of sweepPayoutId.

SWEEP_PAYOUT_STARTED

Sent when a sweep payout withdrawal has been initiated.

SWEEP_PAYOUT_COMPLETED

Sent when all steps of a sweep payout have been completed and funds have been delivered.

SWEEP_PAYOUT_INTERNAL_TRANSFER_FAILED

Sent when a sweep payout cannot be completed due to insufficient funds in the beneficiary's balance.

Other events

RECIPIENT_DATA_UPDATE_REQUIRED

Sent when we receive a Notice of Change (NOC) from the banking network indicating that the recipient's bank account details need to be corrected. You should prompt your end user to update their bank account information.

NOC data object

{
  "operation": "RECIPIENT_DATA_UPDATE_REQUIRED",
  "resourceId": "632a208b806bd70097197367",
  "createdAt": "2024-09-21T10:00:00.000000",
  "integratorId": "6306548828912548710e667c",
  "success": false,
  "message": "C01 - Incorrect Account Number",
  "data": {
    "transactionId": "632a208b806bd70097197367",
    "recipientId": "rec-abc-123",
    "nocMessage": "C01 - Incorrect Account Number"
  }
}