Saltar al contenido principal
Lo primero que debes hacer para usar los webhooks de Fintoc es construir tu propio endpoint de webhook. Construir un endpoint de webhook es similar a construir cualquier endpoint para tu aplicación, pero creemos que es importante tener algunas consideraciones en mente antes de empezar a escribir código. También te recomendamos que leas nuestra guía sobre buenas prácticas para implementar webhooks.

Consideraciones clave

Para cada evento que ocurre en Fintoc, se enviará una solicitud HTTP (POST) en formato JSON a cada endpoint de webhook registrado. Desde esa solicitud puedes parsear el detalle completo del evento usando el body en JSON. Tu endpoint de webhook, entonces, debe ser capaz de recibir solicitudes POST, manejar la información del evento y luego responder con cualquier código de respuesta HTTP que pertenezca a la familia de códigos de éxito (2XX).

Guardar el evento recibido

Cada evento enviado por Fintoc como webhook tiene un id único. Es importante al menos guardar el id correspondiente a cada evento en la base de datos de tu aplicación. De esta forma puedes asegurar idempotencia en los eventos recibidos.

Responder 2XX rápidamente

Para confirmar que un evento se recibió correctamente, tu aplicación debe responder con un código de estado HTTP 2XX. Cualquier respuesta con un código de estado distinto será considerada un intento fallido. Si Fintoc no recibe un código de estado 2XX, intentaremos notificar el evento nuevamente. Después de múltiples días e intentos fallidos, Fintoc dejará de enviar el evento a ese endpoint de webhook. Es muy importante que respondas con un código de estado 2XX lo más rápido posible. Cualquier lógica compleja en tu aplicación que se gatille por la recepción de un webhook debería ejecutarse de forma asíncrona. De esta manera, evitamos notificarte múltiples veces sobre eventos que ya fueron recibidos, pero que no lograron responder con un código 2XX debido a un timeout HTTP.

Probar el webhook

Debido a que las notificaciones al endpoint de webhook ocurren solo bajo circunstancias específicas, es posible que algunos bugs en la recepción de un webhook pasen desapercibidos hasta que sea demasiado tarde. Por eso siempre recomendamos que pruebes tus endpoints al:
  • Crear un endpoint de webhook
  • Registrar un endpoint de webhook
  • Realizar cualquier cambio que pueda afectar la recepción del webhook

Código de ejemplo