Saltar al contenido principal
Construye un webhook endpoint para recibir y procesar eventos de Fintoc. Un webhook endpoint funciona como cualquier otro endpoint de tu aplicación, con consideraciones adicionales de entrega y reintentos. Revisa las Buenas prácticas con webhooks antes de implementar tu endpoint.

Consideraciones clave

Cuando ocurre un evento, Fintoc envía una solicitud POST con un body JSON a cada webhook endpoint registrado. Analiza el body JSON para acceder al detalle del evento. Tu webhook endpoint debe procesar la solicitud POST y devolver un código de estado dentro del rango 2xx.

Guarda el evento recibido

Cada evento de webhook enviado por Fintoc tiene un id único. Guarda el id de cada evento en la base de datos de tu aplicación. Usa el id guardado para detectar entregas duplicadas y procesar cada evento una sola vez.

Devuelve un código de estado 2xx antes del timeout

Para confirmar la recepción de un evento, responde con un código de estado HTTP 2xx. Fintoc trata cualquier otro código de estado como un intento fallido. Responde con un código de estado 2xx antes de que expire el timeout de entrega de Fintoc. Ejecuta de forma asíncrona la lógica que no necesita completarse antes de la confirmación, para que el handler responda antes del timeout.

Maneja los reintentos y las entregas fallidas

Fintoc trata una entrega como un intento fallido si tu endpoint responde con cualquier código de estado fuera del rango 2xx o si la solicitud excede el timeout. Cuando una entrega falla, Fintoc la reintenta automáticamente usando backoff exponencial, comenzando 3 segundos después del intento fallido. Fintoc realiza hasta 17 reintentos por cada evento. Si todos los intentos fallan, Fintoc deja de reintentar ese evento. Se aplican las siguientes limitaciones:
  • Fintoc no deshabilita el webhook endpoint automáticamente ni te notifica cuando deja de reintentar un evento.
  • Fintoc no ofrece reenvío manual ni un mecanismo de dead-letter para reenviar un evento fallido.
Fintoc puede entregar el mismo evento más de una vez, por lo que tu endpoint debe ser idempotente. Para manejar eventos duplicados, revisa Evita la duplicación de eventos.

Prueba el webhook

Fintoc envía eventos de webhook solo cuando ocurre la acción subyacente. Por eso, un bug en el handler puede pasar desapercibido hasta que el endpoint recibe tráfico de producción. Prueba tu endpoint cuando lo crees, lo registres o cambies la forma en que recibe eventos. Para conocer el procedimiento de prueba paso a paso, incluyendo cómo exponer tu endpoint local y enviar un evento de prueba, revisa Prueba tu webhook endpoint.

Código de ejemplo

Manejador de webhooks (Python)
Manejador de webhooks (Node.js)