Webhooks

ONVO usa webhooks para notificar a tu aplicación cuando se produce un resultado procesando una intención de pago, un cargo recurrente, una sesión de checkout o una transferencia entrante.

Para recibirlos, configurá una URL de callback en tu cuenta de ONVO. Enviaremos una petición POST a esa URL cada vez que se procese un evento soportado. El payload incluye un atributo type, que identifica el evento, y un objeto data con la información relacionada.

Referencia API relacionada

• Intenciones de pago
• Cargos recurrentes
• Sesiones de Checkout
• SINPE Móvil

Flujo recomendado

1. Exponé un endpoint HTTPS.
2. Registrá el endpoint en el Dashboard de ONVO, en la sección de desarrolladores.
3. Verificá el origen del evento con el secret del webhook.
4. Procesá el evento de forma idempotente.
5. Respondé con estado 2xx cuando el procesamiento sea correcto.

Eventos soportados

Evento	Cuándo ocurre
payment-intent.succeeded	Una intención de pago se procesa con éxito.
payment-intent.failed	Una intención de pago falla.
payment-intent.deferred	Una intención de pago queda a la espera de aprobación, por ejemplo en un flujo SINPE.
subscription.renewal.succeeded	Un cargo recurrente se renueva con éxito.
subscription.renewal.failed	La renovación de un cargo recurrente falla.
checkout-session.succeeded	Una sesión de checkout se procesa con éxito.
mobile-transfer.received	Se recibe una transferencia entrante en un número SINPE Móvil personalizado.

mobile-transfer.received es una notificación adicional para comercios con esta funcionalidad activa. No representa por sí sola un pago satisfactorio y no se envía por defecto. Para habilitarla, contactá a soporte.

Seguridad

Cada webhook tiene un secret asignado. Podés verlo en el Dashboard de ONVO junto a la configuración del webhook.

ONVO incluye ese valor en el header X-Webhook-Secret. El backend genera secrets con el prefijo webhook_secret_. Usalo para verificar que la solicitud viene de ONVO antes de procesar el evento.

X-Webhook-Secret: webhook_secret_...

Respuestas y errores

Cuando un evento representa un error, el objeto del payload puede incluir un atributo error. Ese objeto puede contener:

Campo	Descripción
message	Descripción legible del error.
code	Código del error, cuando aplica.
type	Tipo de error, cuando aplica.

Tu endpoint debe responder con un código 2xx solamente cuando el evento fue recibido y procesado correctamente. Si respondés con otro estado, ONVO puede reintentar el envío.

Tu sistema debe tolerar reintentos y eventos recibidos fuera de orden.