Saltar al contenido principal
Los webhooks permiten que VelaFi envíe notificaciones en tiempo real a tu servidor en el momento en que ocurre algo importante: una orden cambia de estado, llegan fondos a tu cuenta o un pago global avanza en su ciclo de vida. En lugar de consultar la API una y otra vez, registras un endpoint HTTPS una sola vez y VelaFi le envía un HTTP POST con un payload JSON cada vez que se dispara un evento al que estás suscrito. Esta guía explica cómo registrar endpoints, verificar la firma de la solicitud y confirmar la entrega.
Los webhooks no se disparan en el entorno sandbox (https://api-test.velafi.com). Prueba la lógica de tu handler de webhooks simulando payloads localmente y después verifica el flujo completo en producción con transacciones de bajo valor.

Tipos de evento disponibles

Registra un webhook por separado para cada tipo de evento que quieras recibir. La creación de un webhook se rechaza si ya existe un webhook activo para ese tipo de evento, y un webhook recibe su evento para todos los comercios de tu cuenta. VelaFi admite los siguientes tipos de evento:

ORDER_WEBHOOK

Se dispara con los cambios de estado de las órdenes de fiat a cripto (on-ramp) y de cripto a fiat (off-ramp) creadas a través de la API.

GLOBAL_PAYMENT_WEBHOOK

Se dispara con los cambios de estado de las órdenes de pagos globales de fiat a fiat creadas a través de la API.

FUNDING_WEBHOOK

Se dispara cuando un registro de fondeo (un depósito fiat, un retiro fiat, una compra de cripto o una transferencia interna en la cuenta fiat (Pending Fund) del comercio) se completa, se cancela o se reembolsa. Los retiros de la billetera cripto se cubren con CRYPTO_WITHDRAW_WEBHOOK.

ON_RAMP_WITHDRAW_WEBHOOK

Se dispara cuando VelaFi ya retiró la cripto de una orden on-ramp completada por API hacia la dirección de billetera de destino de la orden.

STABLE_COIN_PAYMENT_WEBHOOK

Se dispara cuando se confirma una orden de pago con stablecoin.

CRYPTO_WITHDRAW_WEBHOOK

Se dispara cuando un retiro de cripto desde la billetera de un comercio es exitoso, falla o se cancela.

Registrar un endpoint de webhook

Verificar la firma del webhook

Cada solicitud que VelaFi envía a tu endpoint incluye un header signature. Su valor es una firma RSA-SHA256 del cuerpo crudo de la solicitud, codificada como cadena hexadecimal. Verifica siempre esta firma antes de procesar el payload para asegurarte de que la solicitud realmente proviene de VelaFi. Los pasos de verificación son:
  1. Extrae el valor de signature del header de la solicitud.
  2. Decodifica de hexadecimal el valor de signature.
  3. Verifícalo como una firma RSA-SHA256 (SHA256withRSA, PKCS#1 v1.5) sobre el cuerpo crudo exacto de la solicitud, usando la publicKey de la respuesta del registro del webhook.
  4. Si la verificación es exitosa, procesa el payload y devuelve {"callbackStatus": "SUCCESS"}.

Esquemas de payload de webhook

Cada tipo de evento entrega un cuerpo JSON distinto a tu endpoint.
VelaFi envía este payload con los cambios de estado de las órdenes de fiat a cripto y de cripto a fiat creadas a través de la API. Este es un ejemplo abreviado; consulta Evento de orden para ver todos los campos.
orderType es BUY para las órdenes on-ramp y SELL para las órdenes off-ramp. Solo se envían algunos estados, y las órdenes rechazadas o vencidas se envían como 70. Consulta Evento de orden para ver los estados que se envían.
VelaFi envía este payload con los cambios de estado de las órdenes de pagos globales de fiat a fiat creadas a través de la API.
orderStatus usa los mismos códigos que el endpoint de detalle de orden de Pagos globales, pero solo se envían los estados listados en Evento de pago global.
VelaFi envía este payload cuando un depósito fiat, un retiro fiat, una compra de cripto o una transferencia interna en la cuenta fiat (Pending Fund) de tu comercio se completa, se cancela o se reembolsa. Los retiros de la billetera cripto se cubren con CRYPTO_WITHDRAW_WEBHOOK.
El campo type es uno de DEPOSIT, WITHDRAW, BUY_CRYPTO, TRANSFER_IN o TRANSFER_OUT. El campo status es 2 (completado), 3 (cancelado) o 4 (reembolsado). Los registros pendientes no se envían.

Confirmar la recepción

Tu endpoint debe devolver una respuesta HTTP 2xx (por ejemplo 200) con el siguiente cuerpo JSON para confirmar que la notificación se recibió y se procesó correctamente. Si VelaFi no recibe una confirmación SUCCESS, por ejemplo porque tu endpoint no respondió en 6 segundos, reintenta la entrega, con un total de tres intentos. Consulta Entrega y reintentos para ver el calendario, el manejo de duplicados y el orden.
Devuelve {"callbackStatus": "SUCCESS"} en cuanto hayas verificado la firma y guardado el evento. Realiza cualquier procesamiento posterior de forma asíncrona para evitar timeouts que puedan provocar reintentos innecesarios.