Saltar al contenido principal
Lo primero que debes hacer para usar los webhooks de Fintoc es construir tu propio webhook endpoint. Construir un webhook endpoint 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 leer nuestra guía sobre buenas prácticas para implementar webhooks.

Consideraciones clave

Por cada evento que ocurre en Fintoc, se enviará una solicitud HTTP POST con JSON a cada webhook endpoint registrado. A partir de esa solicitud, puedes parsear todo el detalle del evento usando el body JSON. Tu webhook endpoint, 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 la idempotencia en los eventos recibidos.

Devolver 2XX rápidamente

Para confirmar que un evento fue recibido exitosamente, tu aplicación debe responder con un código de estado HTTP 2XX. Cualquier respuesta con un código de estado distinto a ese será considerada un intento fallido. Si Fintoc no recibe un código de estado 2XX, intentaremos notificar el evento nuevamente. Después de varios días e intentos fallidos, Fintoc dejará de enviar el evento a ese webhook endpoint. 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 disparada por la recepción de un webhook debe ejecutarse de forma asíncrona. De esta forma, evitamos notificarte múltiples veces sobre eventos que ya han sido recibidos, pero que no lograron responder con un código de estado 2XX debido a un timeout HTTP.

Probar el webhook

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

Código de ejemplo