Lo que conviene saber - Limitaciones de webhooks y comportamiento del sistema

Entender cómo finlight maneja los errores, reintentos y limitaciones de los webhooks te ayuda a crear integraciones más fiables y a gestionar tu cuota de forma eficaz.

Manejo de errores y reintentos

Lógica de reintentos

Cuando una entrega de webhook falla, finlight reintenta la solicitud automáticamente:

Programación de reintentos:

• 1.er reintento: Inmediatamente después del fallo inicial
• 2.º reintento
• 3.er reintento

Máximo de intentos:

• Un total de 3 intentos de entrega por evento de webhook
• Cada reintento usa la misma carga y los mismos encabezados
• Todos los intentos de reintento se registran en tu historial de llamadas

Qué desencadena los reintentos

Los reintentos ocurren ante:

• Códigos de error HTTP respuestas 4xx y 5xx
• Tiempos de espera de red (límite de 5 segundos)
• Fallos de conexión (errores de DNS, conexiones rechazadas)
• Errores SSL/TLS (problemas de certificado)

Qué no desencadena reintentos

No hay reintentos ante:

• Respuestas HTTP 2xx (consideradas exitosas)
• Configuración de webhook inválida (URLs malformadas)
• Webhooks deshabilitados

Protección de desactivación automática

Seguimiento de fallos consecutivos

finlight rastrea los fallos consecutivos de webhook para proteger tu cuota y evitar intentos fallidos interminables.

Cómo funciona:

1. El éxito reinicia el contador - Cualquier entrega exitosa (HTTP 2xx) reinicia el contador de fallos a 0
2. Los fallos incrementan el contador - Cada entrega fallida aumenta el recuento de fallos consecutivos
3. Desactivación automática a las 10 - Tras 10 fallos consecutivos, el webhook se deshabilita automáticamente

Comportamiento de la desactivación automática

Cuándo se activa la desactivación automática:

• 10 entregas fallidas consecutivas en todos los intentos de reintento
• El estado del webhook cambia de "habilitado" a "deshabilitado"
• Aparece una notificación en el panel que indica la desactivación automática
• No hay más intentos de webhook hasta volver a habilitarlo manualmente

Notas importantes:

• Solo los fallos consecutivos cuentan para la desactivación automática
• Cualquier entrega exitosa reinicia el contador a 0
• Se requiere volver a habilitar manualmente: los webhooks no se habilitan solos
• Todos los tipos de fallo cuentan (tiempos de espera, respuestas 4xx, 5xx)

Escenarios de ejemplo

Escenario 1: Reinicio del contador

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

Escenario 2: Desactivación automática

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled

Recuperación y rehabilitación

Proceso de rehabilitación manual

Pasos para rehabilitar:

1. Identifica la causa raíz usando el historial de llamadas
2. Corrige los problemas del endpoint (autenticación, URL, errores del servidor)
3. Rehabilita el webhook en el detalle del webhook editando el ajuste de estado
4. Prueba el webhook manualmente con el botón de prueba del panel
5. Monitorea las entregas iniciales para confirmar la resolución

Estrategias de prevención

Evitar la desactivación automática:

• Implementa un manejo de errores adecuado en tu endpoint
• Devuelve códigos de estado HTTP apropiados
• Monitorea la salud del webhook de forma proactiva
• Configura alertas para los fallos de webhook
• Prueba los cambios en desarrollo antes de producción

Gestión de cuotas

Puedes ver tu uso en el gráfico del panel. Ten en cuenta que el uso se registra con retraso.

Las solicitudes fallidas cuentan para la cuota

Importante: Todos los intentos de entrega de webhook cuentan para la cuota de tu suscripción, incluidas las entregas fallidas.

Qué cuenta:

• Intentos de entrega iniciales - cuentan para la cuota
• Todos los intentos de reintento - cada reintento cuenta por separado
• Entregas fallidas - aún consumen cuota
• Solicitudes de prueba de webhook - también cuentan para la cuota

Ejemplo de impacto en la cuota:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

Gestionar la cuota de forma eficiente

Mejores prácticas:

• Corrige rápido los problemas del endpoint para minimizar los reintentos fallidos
• Monitorea el historial de llamadas en busca de patrones de fallo
• Prueba a fondo antes de habilitar webhooks en producción
• Usa un manejo de errores adecuado para devolver los códigos de estado correctos

Protección de cuota: La función de desactivación automática ayuda a evitar el desperdicio de cuota al detener las entregas a endpoints que fallan de forma constante.

Para orientación sobre la configuración de webhooks, consulta la documentación principal de webhooks. Para pruebas y depuración, consulta la guía de pruebas.