Crypto Withdrawal Event

When a crypto withdrawal from one of your merchant wallets reaches a final status, VelaFi sends a signed HTTP POST request to your CRYPTO_WITHDRAW_WEBHOOK endpoint. Verify the signature header and respond with {"callbackStatus": "SUCCESS"} to acknowledge receipt. The event covers:

Withdrawals to external addresses created with Create Crypto Withdrawal or in the VelaFi dashboard.
Mass payout items sent to external addresses.
Automatic withdrawals of on-ramp orders to the order’s destination address. These also trigger ON_RAMP_WITHDRAW_WEBHOOK when they succeed, so if you subscribe to both event types you receive two notifications for the same transfer.

It is not sent for:

Withdrawals to a VelaFi wallet address created with Create Crypto Withdrawal or in the dashboard. These are booked as internal transfers and appear in Crypto Transfer History.
Stablecoin payment refunds, even though they appear in Get Crypto Withdrawal History.
Withdrawals that are still in progress, waiting for approval, or under review. Only final statuses are sent.

Register this event type with Create Webhook using "eventType": "CRYPTO_WITHDRAW_WEBHOOK". As with all event types, one webhook receives the event for every merchant under your account, and webhooks are not triggered in the sandbox.

Request Headers

Header	Description
`signature`	RSA-SHA256 signature of the raw request body, hex-encoded. Use your webhook’s `publicKey` to verify. See Webhook Setup.
`Content-Type`	`application/json`

Payload Fields

All values are sent as JSON strings.

string

The ID of the webhook the event was queued for.

string

Always CRYPTO_WITHDRAW_WEBHOOK for this event type.

string

Withdrawal record ID. It matches the orderId returned by Create Crypto Withdrawal and by Get Crypto Withdrawal History.

string

The clientId of the withdrawal: the value you supplied in Create Crypto Withdrawal, or the on-ramp orderId for an automatic on-ramp withdrawal. All items of a mass payout share the same value, in the format masspayout:<id>. Empty if the withdrawal has none.

string

Your VelaFi account (user) ID.

string

Merchant whose wallet was debited.

string

Token symbol, for example USDT.

string

Network of the withdrawal, for example TRC20. This is the same value as chainType in Get Withdrawal Quota.

string

Destination address.

string

Withdrawal amount (the same value as cryptoAmount in Get Crypto Withdrawal History).

string

Network fee, in the same token as crypto. Always 0 for automatic on-ramp withdrawals.

string

amount minus fee (the same value as arriveCryptoAmount in Get Crypto Withdrawal History).

string

Final result of the withdrawal:

SUCCESS — the withdrawal was completed on-chain.
FAILED — the withdrawal failed or was rejected by VelaFi, and the amount was returned to the wallet balance.
REFUNDED — the funds had already left VelaFi’s wallet, came back, and were returned to the wallet balance. Handle it the same way as FAILED.
CANCELLED — the withdrawal was cancelled in the VelaFi dashboard before it was sent, and the amount was returned to the wallet balance. The Open API has no cancel endpoint.

string

The matching status code from Get Crypto Withdrawal History: 6 for SUCCESS, 7 for FAILED and REFUNDED, and 9 for CANCELLED.

string

On-chain transaction hash. Only included when status is SUCCESS.

string

Time the withdrawal was created (Unix timestamp in milliseconds).

string

Time the withdrawal reached its final status (Unix timestamp in milliseconds).

string

Unix timestamp (milliseconds) at which this delivery attempt was signed.

Example Payloads

SUCCESS
FAILED

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "CRYPTO_WITHDRAW_WEBHOOK",
  "withdrawId": "512345678901234567",
  "clientId": "withdraw-0001",
  "userId": "455472",
  "merchantId": "100001",
  "crypto": "USDT",
  "network": "TRC20",
  "address": "YOUR_DESTINATION_ADDRESS",
  "amount": "100",
  "fee": "1",
  "netAmount": "99",
  "status": "SUCCESS",
  "statusCode": "6",
  "txHash": "4a7f0c3e2b1d9f8e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f",
  "createTime": "1735279907000",
  "completeTime": "1735280100000",
  "timestamp": "1735280101000"
}

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "CRYPTO_WITHDRAW_WEBHOOK",
  "withdrawId": "512345678901234568",
  "clientId": "withdraw-0002",
  "userId": "455472",
  "merchantId": "100001",
  "crypto": "USDT",
  "network": "TRC20",
  "address": "YOUR_DESTINATION_ADDRESS",
  "amount": "100",
  "fee": "1",
  "netAmount": "99",
  "status": "FAILED",
  "statusCode": "7",
  "createTime": "1735279907000",
  "completeTime": "1735283507000",
  "timestamp": "1735283508000"
}

Required Response

Return an HTTP 2xx status (for example 200) with the following JSON body to acknowledge receipt:

Your response

{
  "callbackStatus": "SUCCESS"
}

Handling Notes

One final event per withdrawal. VelaFi sends the event once a withdrawal reaches a final status. Intermediate states, such as approval or review, are not sent. To check a withdrawal before it is final, use Get Crypto Withdrawal History.
Duplicates. The same event can arrive more than once, so deduplicate on withdrawId and status. See Delivery and Retries.
Reconcile missed events. If your endpoint misses all delivery attempts, the event is not redelivered. Reconcile pending withdrawals against Get Crypto Withdrawal History, matching on clientId or, for mass payout items, on withdrawId (orderId in the history). Don’t keep a user’s balance locked on your side indefinitely.
Replacing a webhook. Unlike other event types, pending deliveries go only to the webhook they were queued for. If you create a new CRYPTO_WITHDRAW_WEBHOOK webhook after deleting or disabling the old one, events still queued for the old webhook are not delivered. To change where events go, update the URL of the existing webhook with Update Webhook instead. A disabled webhook’s pending events are delivered if you re-enable that same webhook without creating another one.

Overview

Account

Configuration

Merchants

Crypto Wallet

Beneficiaries

Quotes

Orders

Webhooks

Crypto Withdrawal Event

Request Headers

Payload Fields

Example Payloads

Required Response

Handling Notes

​Request Headers

​Payload Fields

​Example Payloads

​Required Response

​Handling Notes

Request Headers

Payload Fields

Example Payloads

Required Response

Handling Notes