Webhooks
ONVO usa webhooks para avisarle a tu servidor cuando algo cambia en tu cuenta: un pago se completa o falla, se abre una disputa, un reembolso termina o una liquidación se paga. Cada evento se envía como una petición POST firmada a los endpoints de webhook que configurás en el Dashboard.
X-Webhook-Secret?Si tu servidor valida el header X-Webhook-Secret y recibe eventos como payment-intent.succeeded, usa el formato anterior de webhooks. Sigue funcionando sin cambios. Cuando quieras pasarte al formato firmado, seguí Migrar al formato firmado.
Cómo funciona
- Algo cambia en tu cuenta, por ejemplo una intención de pago se completa.
- ONVO crea un evento con un ID estable (
evt_...) y una copia de los campos públicos del objeto en ese momento. - ONVO envía una entrega (
whd_...) del evento a cada endpoint activo suscrito a ese tipo de evento, en el mismo modo (prueba o producción). - Cada petición HTTP es un intento (
wha_...). Si tu endpoint no responde con2xx, ONVO reintenta la entrega.
Consultá la lista completa en Eventos.
Crear un endpoint
Los endpoints se administran desde el Dashboard, en Desarrolladores > Webhooks. No se pueden crear ni modificar con llaves API. Lo pueden hacer los miembros con rol de propietario, administrador o desarrollador.
- Elegí Agregar webhook.
- Seleccioná los eventos que necesita tu integración. Seleccionar todos guarda la lista actual: los tipos de evento que ONVO agregue en el futuro no se suscriben automáticamente.
- Ingresá la URL del endpoint, un nombre (hasta 100 caracteres) y, si querés, una descripción (hasta 300 caracteres).
- Guardá el secreto de firma (
whsec_...). Se muestra completo al crear el endpoint y después podés volver a verlo con Revelar secreto de firma, hasta 5 veces por minuto. Tratalo como una contraseña. - Usá Probar conexión para enviar un evento de prueba firmado (
webhook_endpoint.test) y confirmar que tu servidor lo verifica y responde2xx.
La URL debe:
- usar
https://en el puerto 443; - usar un nombre de dominio, no una dirección IP;
- resolver solo a direcciones IP públicas (no se aceptan direcciones privadas, locales ni reservadas). Un dominio que no resuelve se rechaza igual que una dirección privada;
- no incluir usuario, contraseña ni un fragmento (
#...); - tener como máximo 2,048 caracteres, con los caracteres especiales ya codificados (un espacio cuenta como
%20); - no apuntar a dominios de ONVO.
Cada URL puede usarse en un solo endpoint por modo. Para comparar URLs, ONVO ignora un ? o un # vacíos al final y los puntos al final del dominio; las mayúsculas de la ruta, una barra final en una ruta no vacía y el orden de los parámetros sí cuentan como URLs distintas. Tampoco podés usar la URL de un webhook del formato anterior que esté activo, ni al crear un endpoint ni al editarlo: para pasar esa URL al formato firmado, usá Actualización disponible en ese webhook y seguí Migrar al formato firmado.
Podés tener hasta 16 endpoints por modo, incluidos los borradores y los desactivados. Los endpoints de modo prueba solo reciben eventos de prueba y los de producción solo reciben eventos de producción.
Formato de la solicitud
ONVO envía cada evento como POST con estos headers:
| Header | Valor |
|---|---|
Content-Type | application/json; charset=utf-8 |
User-Agent | ONVO-Webhooks |
X-Onvo-Signature | Firma de la petición, por ejemplo t=1785758400,v1=5257a8.... Ver Verificar firmas. |
X-Onvo-Event-Id | ID del evento (evt_...). Es el mismo en todos los endpoints, reintentos y reenvíos. |
X-Onvo-Delivery-Id | ID de la entrega a este endpoint (whd_...). Un reenvío manual crea una entrega nueva. |
X-Onvo-Attempt-Id | ID de este intento HTTP (wha_...). Cada intento tiene un ID y una firma nuevos. |
El cuerpo es un sobre JSON con el evento:
{
"id": "evt_vx7r5r6m33g2x9m2p8j2k1a4",
"object": "event",
"createdAt": "2026-10-21T16:10:01.000Z",
"mode": "live",
"accountId": "clacct0001",
"type": "payment_intent.succeeded",
"data": {
"object": {
"object": "payment_intent",
"id": "clpiment0001",
"amount": 500000,
"currency": "CRC",
"status": "succeeded",
"createdAt": "2026-10-21T16:09:50.000Z",
"updatedAt": "2026-10-21T16:10:01.000Z"
}
}
}
| Campo | Descripción |
|---|---|
id | ID del evento. Usalo para descartar duplicados. |
object | Siempre event. |
createdAt | Fecha del evento, en ISO 8601 y UTC. |
mode | test o live. |
accountId | Cuenta de ONVO que recibe el evento, normalmente la cuenta donde ocurrió. Los eventos de un pago de marketplace hecho en nombre de una cuenta conectada (onBehalfOf), incluidos los de sus reembolsos y disputas, van a la cuenta de la plataforma; la cuenta conectada no los recibe. |
type | Tipo de evento, por ejemplo refund.succeeded. |
data.object | Campos públicos del objeto al momento del evento. Su campo object indica el tipo de recurso. |
data.previousAttributes | Solo en dispute.updated y dispute.closed: los campos que cambiaron, con su valor anterior. No se incluye cuando la disputa se abrió ya resuelta. |
Los montos son enteros en la unidad mínima de la moneda: 500000 en CRC representa ₡5,000.00. Los campos opcionales sin valor se omiten y un valor vacío explícito llega como null. ONVO puede agregar campos opcionales nuevos, así que tu código debe ignorar los que no conoce.
Responder a ONVO
- Verificá la firma con el cuerpo crudo de la petición antes de procesarla.
- Respondé con un estado
2xxdentro de 10 segundos. Guardá el evento y hacé el trabajo pesado después, en segundo plano. - Respondé
2xxtambién a los tipos de evento que tu código no maneja, para no generar reintentos innecesarios. - ONVO no sigue redirecciones: una respuesta
3xxcuenta como fallida. - El cuerpo de tu respuesta no se procesa. De los intentos fallidos, ONVO guarda hasta 16 KiB de la respuesta para que la veas en el registro de entregas.
Reintentos
Una entrega se reintenta si tu endpoint responde con un estado distinto de 2xx, no responde en 10 segundos o la conexión falla.
| Modo | Reintentos |
|---|---|
| Producción | Con espera exponencial durante un máximo de 72 horas. |
| Prueba | Hasta tres reintentos durante un máximo de 24 horas. |
Si respondés 429 o 503 con un header Retry-After, ONVO espera al menos ese tiempo antes del próximo intento, hasta un máximo de 12 horas en producción y 6 horas en prueba. Si el header pide más, ONVO espera ese máximo. Una entrega no se reintenta cuando el destino no cumple las reglas de URL o cuando el evento supera 1 MiB.
Pausa y bloqueo automáticos
Después de 10 intentos fallidos seguidos, ONVO pausa las entregas automáticas a ese endpoint y lo marca como Pausado. Los eventos nuevos quedan en espera y ONVO vuelve a probar el endpoint con una de esas entregas después de un tiempo, que crece hasta un máximo de una hora. Cuando un intento tiene éxito, las entregas se reanudan.
Si una entrega llega a un destino que ya no cumple las reglas de URL, por ejemplo porque el dominio ahora resuelve a una dirección privada, esa entrega falla sin reintentos y el endpoint queda Bloqueado. Las entregas automáticas siguientes quedan en espera y ONVO no vuelve a probar el endpoint por su cuenta: solo las libera una Probar conexión exitosa o un reenvío manual que llega con éxito. Para activar un endpoint bloqueado también necesitás una prueba de conexión exitosa.
Cambiar la URL de un endpoint pausado o bloqueado, o cambiar su estado, no libera las entregas en espera. Se liberan cuando una entrega llega con éxito a la URL nueva: una prueba de conexión, un reenvío manual o, si el endpoint está pausado, su próxima prueba programada. Después de corregir la URL de un endpoint bloqueado, usá Probar conexión.
Las entregas no quedan en espera para siempre: las que siguen en espera cuando termina su período de reintentos (72 horas en producción y 24 en prueba, desde que se crearon) fallan con retry_horizon_expired. Después solo podés recuperarlas con un reenvío manual, dentro de los 15 días siguientes al evento.
En producción, ONVO envía un correo a los propietarios, administradores y desarrolladores de la cuenta, y a quien creó el endpoint, cuando el endpoint se pausa o se bloquea, y cuando se recupera de una pausa. La salida de un bloqueo no envía correo.
Desactivar un endpoint
Un endpoint desactivado no recibe eventos. ONVO no crea entregas para los eventos que ocurren mientras está inactivo, ni siquiera cuando lo volvés a activar. Sus entregas pendientes y reintentos en cola fallan con endpoint_inactive cuando les toca el próximo intento, y volver a activarlo después no las recupera. Con el endpoint activo, podés reenviarlas manualmente durante 15 días.
Para detener las entregas por un rato, por ejemplo durante un mantenimiento, no desactives el endpoint: respondé 503 con un header Retry-After y ONVO reintenta más tarde, dentro del período de reintentos.
Duplicados y orden
- Las entregas son al menos una vez: tu servidor puede recibir el mismo evento más de una vez, por ejemplo después de un error de red o de un reenvío manual. Descartá duplicados con el
iddel evento, no con el ID de entrega ni de intento. - Los eventos no llegan en un orden garantizado. Cuando el orden importa, compará el
updatedAtdel objeto o consultá su estado actual en la API antes de actuar. Las renovaciones no tienenupdatedAt: usáattemptCountylastPaymentAttempt.
Registro de entregas y reenvíos
En el detalle de cada endpoint podés ver sus entregas, el resultado de cada intento y el cuerpo exacto que se envió. Podés filtrar por estado, tipo de evento y fechas; las fechas son días completos en la zona horaria del país de tu cuenta. La búsqueda acepta el ID completo de una entrega (whd_...), de un evento (evt_...) o del objeto del evento, o el inicio de un tipo de evento, por ejemplo refund.. No encuentra partes de un ID y necesita al menos 3 caracteres.
Podés reenviar una entrega durante los 15 días siguientes a la creación del evento, si el endpoint está activo. El reenvío manda el mismo evento, con el mismo id y el mismo cuerpo, a la URL actual del endpoint, con una firma nueva. Es un solo intento, sin reintentos automáticos, y se envía aunque el endpoint esté pausado o bloqueado. Cada evento puede tener un solo reenvío en curso por endpoint. Podés reenviar hasta 10 entregas por minuto por endpoint y hasta 100 por hora por cuenta y modo.
ONVO conserva el detalle de eventos, entregas e intentos durante 180 días. Las respuestas guardadas de intentos fallidos se eliminan a los 30 días.
Rotar el secreto de firma
Desde el detalle del endpoint podés rotar el secreto de firma. Durante las 24 horas siguientes, cada petición incluye una firma con el secreto nuevo y otra con el anterior, así que tu servidor sigue validando mientras actualizás su configuración. Si alguien más pudo ver el secreto, rotalo de inmediato.
- Mientras el secreto anterior siga vigente, no podés volver a rotarlo.
- Cada miembro puede rotar el secreto de un endpoint hasta 3 veces por hora.
- Rotar el secreto, igual que cambiar la URL del endpoint, invalida la última prueba de conexión exitosa. Un reemplazo en borrador necesita una prueba nueva antes de activarse.
Próximos pasos
- Eventos: tipos de evento y campos de cada objeto.
- Verificar firmas: algoritmo y ejemplos en Node.js, PHP y Python.
- Migrar al formato firmado: cómo reemplazar un webhook del formato anterior.