Webhooks

¿Qué son los Webhooks?

Los webhooks son una forma en la que puedes recibir eventos de todas las novedades que ocurren en Ibis Negocios. Esto significa que, por cada on-ramp u off-ramp recibirás las notificaciones en tiempo real.

Estos son todos los eventos que puedes recibir:

Comportamiento de los webhooks

• Método y formato: Ibis envía una petición HTTP POST a la URL de webhook que configures. El cuerpo del mensaje es JSON con el evento y sus atributos.
• Entregas y reintentos: ante una respuesta no exitosa (códigos 5xx, timeouts o errores de red), reintentamos la entrega hasta un máximo de 12 veces.
• Backoff: aplicamos backoff exponencial iniciando con un delay base de 1 segundo entre intentos. El tiempo entre reintentos se incrementa exponencialmente a partir de ese valor.
• Éxito: consideramos la entrega como exitosa si tu endpoint responde con un status 2xx dentro del tiempo de espera.
• Idempotencia: cada evento incluye un identificador único que puedes usar para asegurar que tu procesamiento sea idempotente en caso de recibir reintentos.
• Timeouts: si tu endpoint tarda demasiado en responder, el intento se marca como fallido y se programa el siguiente conforme al backoff. (30s)
• Seguridad: en cada request incluimos el header x-ibis-webhook-secret para que puedas validar la procedencia antes de procesar el evento.

Consideraciones de seguridad

En todos nuestros requests de webhook incluimos el header x-ibis-webhook-secret con el secreto de verificación asignado a tu integración. Este Webhook Secret, junto con tu API Key (para sandbox y/o producción), será enviado por nuestro equipo vía correo electrónico.

Con estos datos podrás validar la autenticidad de los webhooks verificando el valor de x-ibis-webhook-secret y autenticar tus llamadas a nuestros endpoints utilizando el API Key provisto.

Sugerimos almacenar ambos valores en un gestor de secretos y no registrarlos en logs. Si requieres rotación de credenciales, contáctanos para coordinar la emisión/rotación de nuevos valores.