> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto Withdrawal Event

> Reference for the CRYPTO_WITHDRAW_WEBHOOK payload VelaFi sends when a crypto withdrawal from a merchant wallet succeeds, fails, or is cancelled.

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](https://docs.velafi.com/api-reference/crypto-wallet/create-crypto-withdrawal.md) 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`](https://docs.velafi.com/api-reference/webhooks/on-ramp-withdraw-message-push) 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](https://docs.velafi.com/api-reference/merchant/query-crypto-transfers.md).
* Stablecoin payment refunds, even though they appear in [Get Crypto Withdrawal History](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md).
* Withdrawals that are still in progress, waiting for approval, or under review. Only final statuses are sent.

> [!NOTE]
>
> Register this event type with [Create Webhook](https://docs.velafi.com/api-reference/webhooks/create-webhook-endpoints.md) 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](https://docs.velafi.com/api-reference/webhooks/webhook-setup.md). |
| `Content-Type` | `application/json` |

## Payload Fields

All values are sent as JSON strings.

**webhookId** `string`

The ID of the webhook the event was queued for.

**eventType** `string`

Always `CRYPTO_WITHDRAW_WEBHOOK` for this event type.

**withdrawId** `string`

Withdrawal record ID. It matches the `orderId` returned by [Create Crypto Withdrawal](https://docs.velafi.com/api-reference/crypto-wallet/create-crypto-withdrawal.md) and by [Get Crypto Withdrawal History](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md).

**clientId** `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.

**userId** `string`

Your VelaFi account (user) ID.

**merchantId** `string`

Merchant whose wallet was debited.

**crypto** `string`

Token symbol, for example `USDT`.

**network** `string`

Network of the withdrawal, for example `TRC20`. This is the same value as `chainType` in [Get Withdrawal Quota](https://docs.velafi.com/api-reference/crypto-wallet/get-withdrawal-quota.md).

**address** `string`

Destination address.

**amount** `string`

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

**fee** `string`

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

**netAmount** `string`

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

**status** `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.

**statusCode** `string`

The matching `status` code from [Get Crypto Withdrawal History](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md): `6` for `SUCCESS`, `7` for `FAILED` and `REFUNDED`, and `9` for `CANCELLED`.

**txHash** `string`

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

**createTime** `string`

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

**completeTime** `string`

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

**timestamp** `string`

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

## Example Payloads

> [tab] SUCCESS
>
> ```json Incoming POST body theme={null}
> {
>   "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"
> }
> ```

> [tab] FAILED
>
> ```json Incoming POST body theme={null}
> {
>   "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:

```json Your response theme={null}
{
  "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](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md).
* **Duplicates.** The same event can arrive more than once, so deduplicate on `withdrawId` and `status`. See [Delivery and Retries](https://docs.velafi.com/api-reference/webhooks/webhook-setup.md#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](https://docs.velafi.com/api-reference/webhooks/update-a-webhook.md) instead. A disabled webhook's pending events are delivered if you re-enable that same webhook without creating another one.


## Related topics

- [List Crypto Withdrawals](https://docs.velafi.com/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)
- [Create a Crypto Withdrawal](https://docs.velafi.com/api-reference/crypto-wallet/create-crypto-withdrawal.md)
- [Funding Event](https://docs.velafi.com/api-reference/webhooks/funding-records-message-push.md)
- [On-Ramp Withdrawal Event](https://docs.velafi.com/api-reference/webhooks/on-ramp-withdraw-message-push.md)
- [Changelog](https://docs.velafi.com/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.