signature. Tu servidor debe verificar esta firma antes de procesar el evento.
Cómo funciona la verificación de la firma
1
Extrae el encabezado de la firma
Lee el encabezado
signature de la solicitud HTTP entrante. El valor es la firma RSA-SHA256 del cuerpo sin procesar de la solicitud, codificada como una cadena hexadecimal.2
Carga tu clave pública
Obtén la
publicKey que se devolvió al crear el endpoint del webhook. También se incluye para cada webhook en la respuesta de Listar webhooks. Es una clave pública RSA codificada en Base64 en formato X.509.3
Calcula y verifica la firma
Usa RSA-SHA256 para verificar la firma con los bytes del cuerpo sin procesar de la solicitud y la clave pública. Decodifica la firma hexadecimal a bytes antes de verificarla.
4
Responde a VelaFi
Devuelve
{"callbackStatus": "SUCCESS"} si la verificación es correcta, o {"callbackStatus": "FAIL"} si no lo es. VelaFi usa esta respuesta para determinar si debe reintentar la entrega.Código de verificación de la firma
- Java
- Python
- JavaScript
Tipos de eventos de webhook
VelaFi admite los siguientes tipos de eventos. Cada uno requiere registrar un endpoint de webhook por separado. La creación de un webhook se rechaza si ya existe un webhook activo para ese tipo de evento. Los webhooks pertenecen a tu cuenta de VelaFi, por lo que un webhook recibe su evento para todos los comercios de la cuenta:ORDER_WEBHOOK
Se dispara cuando una orden de fiat a cripto o de cripto a fiat creada mediante la API cambia de estado.
GLOBAL_PAYMENT_WEBHOOK
Se dispara cuando una orden de pago global de fiat a fiat creada mediante la API cambia de estado.
FUNDING_WEBHOOK
Se dispara cuando un registro de fondeo (un depósito, retiro, compra de cripto o transferencia interna) se completa, se cancela o se reembolsa.
ON_RAMP_WITHDRAW_WEBHOOK
Se dispara cuando el retiro de cripto de una orden on-ramp completada por API hacia la dirección de billetera de destino de la orden es exitoso.
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 una billetera del comercio es exitoso, falla o se cancela.
Entrega y reintentos
Cada entrega es un HTTP POST con un cuerpo JSON y un encabezadosignature. Cada payload contiene estos campos además de los campos específicos del evento:
Los valores del payload se envían como cadenas JSON, incluidos los IDs, los montos y las marcas de tiempo.
- Confirmación de recepción. Una entrega cuenta como exitosa solo cuando tu endpoint devuelve un estado HTTP
2xxy un cuerpo con un objeto JSON cuyocallbackStatusesSUCCESS. Cualquier otro estado o cuerpo cuenta como un intento fallido. VelaFi usa tiempos de espera de 6 segundos para conexión, escritura y lectura, y un tiempo de espera agotado también cuenta como intento fallido. - Reintentos. Una entrega fallida normalmente se reintenta de forma automática, con un total de tres intentos. El segundo intento se hace entre 5 y 10 minutos después del primer fallo, y el tercero entre 60 y 65 minutos después del segundo fallo. Después del tercer intento fallido, el evento ya no se reintenta. La Open API no tiene un endpoint para solicitar una nueva entrega.
- Duplicados. El mismo evento puede entregarse más de una vez. Por ejemplo, si tu endpoint procesa una entrega pero su respuesta no se recibe a tiempo, el evento se reintenta. Haz que tu handler sea idempotente usando como clave el tipo de evento, el ID del registro (
orderId,txIdowithdrawId) y el estado. - Orden y estados omitidos. VelaFi no garantiza que las entregas lleguen en el orden en que ocurrieron los estados. Para
ORDER_WEBHOOK,GLOBAL_PAYMENT_WEBHOOK,FUNDING_WEBHOOKyON_RAMP_WITHDRAW_WEBHOOK, VelaFi revisa el estado actual del registro antes de cada intento. Si el estado cambió desde que el evento se puso en cola, ese evento se descarta y no se entrega, por lo que es posible que no recibas todos los estados intermedios. Consulta la orden o el registro de fondeo para leer su estado más reciente.CRYPTO_WITHDRAW_WEBHOOKse envía solo para el estado final de un retiro. - Solo webhooks activos. Los eventos se ponen en cola solo mientras exista un webhook activo (estado
10) para el tipo de evento. Los eventos que ocurren mientras no hay un webhook activo no se ponen en cola y no se entregan después. Los eventos que ya estaban en cola no se cancelan cuando un webhook se desactiva o se elimina: se retienen y, si vuelve a existir un webhook activo para el mismo tipo de evento en un plazo aproximado de 15 días, se entregan a la URL de ese webhook con suwebhookIdoriginal. Los eventosCRYPTO_WITHDRAW_WEBHOOKson la excepción: se entregan solo al webhook para el que se pusieron en cola, por lo que no se entregan a un webhook nuevo que crees después de eliminar o desactivar el anterior.