Saltar al contenido principal
VelaFi envía notificaciones de eventos a la URL que registraste como solicitudes HTTP POST con payloads JSON. Para proteger tu endpoint de solicitudes falsificadas, VelaFi firma cada payload de webhook con RSA-SHA256 e incluye la firma codificada en hexadecimal en el encabezado de la solicitud 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.
Verifica siempre la firma antes de actuar sobre un payload de webhook. Procesar eventos no verificados puede exponer tu sistema a ataques de repetición y a cambios de estado fraudulentos.

Código de verificación de la firma

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.
Guarda de forma segura la publicKey que se devuelve al crear el webhook. La necesitas en cada verificación. Si la pierdes, llama a Listar webhooks, que devuelve la publicKey de cada webhook.

Entrega y reintentos

Cada entrega es un HTTP POST con un cuerpo JSON y un encabezado signature. 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 2xx y un cuerpo con un objeto JSON cuyo callbackStatus es SUCCESS. 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, txId o withdrawId) 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_WEBHOOK y ON_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_WEBHOOK se 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 su webhookId original. Los eventos CRYPTO_WITHDRAW_WEBHOOK son 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.