> ## 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.

# Evento de retiro cripto

> Referencia del payload CRYPTO_WITHDRAW_WEBHOOK que VelaFi envía cuando un retiro cripto desde la billetera de un comercio es exitoso, falla o se cancela.

Cuando un retiro cripto desde una de las billeteras de tu comercio llega a un estado final, VelaFi envía una solicitud HTTP POST firmada a tu endpoint de `CRYPTO_WITHDRAW_WEBHOOK`. Verifica el header `signature` y responde con `{"callbackStatus": "SUCCESS"}` para confirmar la recepción.

El evento cubre:

* Retiros a direcciones externas creados con [Crear retiro cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/create-crypto-withdrawal.md) o en el panel de VelaFi.
* Elementos de pagos masivos enviados a direcciones externas.
* Retiros automáticos de órdenes de on-ramp a la dirección de destino de la orden. Estos también disparan [`ON_RAMP_WITHDRAW_WEBHOOK`](https://docs.velafi.com/es/api-reference/webhooks/on-ramp-withdraw-message-push) cuando son exitosos, así que si te suscribes a ambos tipos de evento recibirás dos notificaciones por la misma transferencia.

No se envía para:

* Retiros a una dirección de billetera de VelaFi creados con Crear retiro cripto o en el panel. Estos se registran como transferencias internas y aparecen en [Historial de transferencias cripto](https://docs.velafi.com/es/api-reference/merchant/query-crypto-transfers.md).
* Reembolsos de pagos con stablecoin, aunque aparezcan en [Obtener historial de retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md).
* Retiros que siguen en curso, esperando aprobación o en revisión. Solo se envían los estados finales.

> [!NOTE]
>
> Registra este tipo de evento con [Crear webhook](https://docs.velafi.com/es/api-reference/webhooks/create-webhook-endpoints.md) usando `"eventType": "CRYPTO_WITHDRAW_WEBHOOK"`. Como con todos los tipos de evento, un webhook recibe el evento para todos los comercios de tu cuenta, y los webhooks no se disparan en el sandbox.

## Headers de la solicitud

| Header | Descripción |
| - | - |
| `signature` | Firma RSA-SHA256 del cuerpo sin procesar de la solicitud, codificada en hexadecimal. Usa la `publicKey` de tu webhook para verificarla. Consulta [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md). |
| `Content-Type` | `application/json` |

## Campos del payload

Todos los valores se envían como cadenas JSON.

**webhookId** `string`

El ID del webhook para el que se encoló el evento.

**eventType** `string`

Siempre `CRYPTO_WITHDRAW_WEBHOOK` para este tipo de evento.

**withdrawId** `string`

ID del registro de retiro. Coincide con el `orderId` que devuelven [Crear retiro cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/create-crypto-withdrawal.md) y [Obtener historial de retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md).

**clientId** `string`

El `clientId` del retiro: el valor que proporcionaste en Crear retiro cripto, o el `orderId` de on-ramp en el caso de un retiro automático de on-ramp. Todos los elementos de un pago masivo comparten el mismo valor, con el formato `masspayout:<id>`. Vacío si el retiro no tiene uno.

**userId** `string`

El ID de tu cuenta (usuario) de VelaFi.

**merchantId** `string`

Comercio cuya billetera se debitó.

**crypto** `string`

Símbolo del token, por ejemplo `USDT`.

**network** `string`

Red del retiro, por ejemplo `TRC20`. Es el mismo valor que `chainType` en [Obtener cuota de retiro](https://docs.velafi.com/es/api-reference/crypto-wallet/get-withdrawal-quota.md).

**address** `string`

Dirección de destino.

**amount** `string`

Monto del retiro (el mismo valor que `cryptoAmount` en Obtener historial de retiros cripto).

**fee** `string`

Comisión de red, en el mismo token que `crypto`. Siempre `0` en los retiros automáticos de on-ramp.

**netAmount** `string`

`amount` menos `fee` (el mismo valor que `arriveCryptoAmount` en Obtener historial de retiros cripto).

**status** `string`

Resultado final del retiro:

* `SUCCESS` — el retiro se completó on-chain.
* `FAILED` — el retiro falló o VelaFi lo rechazó, y el monto se devolvió al saldo de la billetera.
* `REFUNDED` — los fondos ya habían salido de la billetera de VelaFi, regresaron y se devolvieron al saldo de la billetera. Manéjalo igual que `FAILED`.
* `CANCELLED` — el retiro se canceló en el panel de VelaFi antes de enviarse, y el monto se devolvió al saldo de la billetera. La Open API no tiene un endpoint de cancelación.

**statusCode** `string`

El código de `status` correspondiente de [Obtener historial de retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md): `6` para `SUCCESS`, `7` para `FAILED` y `REFUNDED`, y `9` para `CANCELLED`.

**txHash** `string`

Hash de la transacción on-chain. Solo se incluye cuando `status` es `SUCCESS`.

**createTime** `string`

Momento en que se creó el retiro (marca de tiempo Unix en milisegundos).

**completeTime** `string`

Momento en que el retiro llegó a su estado final (marca de tiempo Unix en milisegundos).

**timestamp** `string`

Marca de tiempo Unix (milisegundos) en la que se firmó este intento de entrega.

## Ejemplos de 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"
> }
> ```

## Respuesta requerida

Devuelve un estado HTTP `2xx` (por ejemplo `200`) con el siguiente cuerpo JSON para confirmar la recepción:

```json Your response theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

## Notas de manejo

* **Un evento final por retiro.** VelaFi envía el evento una vez que un retiro llega a un estado final. Los estados intermedios, como aprobación o revisión, no se envían. Para consultar un retiro antes de que sea final, usa [Obtener historial de retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md).
* **Duplicados.** El mismo evento puede llegar más de una vez, así que deduplica por `withdrawId` y `status`. Consulta [Entrega y reintentos](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md#delivery-and-retries).
* **Concilia los eventos perdidos.** Si tu endpoint pierde todos los intentos de entrega, el evento no se vuelve a entregar. Concilia los retiros pendientes con Obtener historial de retiros cripto, haciendo coincidir por `clientId` o, para los elementos de pagos masivos, por `withdrawId` (`orderId` en el historial). No mantengas bloqueado indefinidamente el saldo de un usuario de tu lado.
* **Reemplazar un webhook.** A diferencia de otros tipos de evento, las entregas pendientes solo van al webhook para el que se encolaron. Si creas un nuevo webhook de `CRYPTO_WITHDRAW_WEBHOOK` después de eliminar o desactivar el anterior, los eventos que siguen encolados para el webhook anterior no se entregan. Para cambiar a dónde van los eventos, actualiza la URL del webhook existente con [Actualizar webhook](https://docs.velafi.com/es/api-reference/webhooks/update-a-webhook.md). Los eventos pendientes de un webhook desactivado se entregan si vuelves a activar ese mismo webhook sin crear otro.


## Related topics

- [Evento de retiro de on-ramp](https://docs.velafi.com/es/api-reference/webhooks/on-ramp-withdraw-message-push.md)
- [Registro de cambios](https://docs.velafi.com/es/docs/changelog.md)
- [Listar retiros cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-withdrawal-history.md)
- [Evento de fondeo](https://docs.velafi.com/es/api-reference/webhooks/funding-records-message-push.md)
- [Crear un retiro cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/create-crypto-withdrawal.md)


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