Confiabilidad y reintentos

Cómo Mosce ERP reintenta la entrega de webhooks fallidos, cuándo desactiva un endpoint automáticamente y cómo rehabilitarlo.

Mosce ERP tiene un sistema de reintentos automáticos que garantiza que los eventos críticos lleguen a tu servidor incluso si hay intermitencias de red o tu servidor está temporalmente inaccesible. Este artículo explica el cronograma de reintentos, cuándo Mosce ERP desactiva un endpoint por fallos repetidos y cómo volver a habilitarlo.

Tiempo de lectura: ~5 min

Cuándo usar esto

Tu servidor estuvo caído por unas horas y quieres saber si los eventos llegaron.
Un webhook aparece como "Deshabilitado" en la configuración y no sabes por qué.
Quieres entender cómo diagnosticar fallos de entrega antes de contactar a soporte.
Necesitas reenviar manualmente un evento que falló.

Antes de empezar

Necesitas el permiso tenant:webhook para ver el historial de entregas y rehabilitar un endpoint.
Ver Configurar un webhook si todavía no tienes un endpoint registrado.

Cronograma de reintentos

Cuando una entrega falla (respuesta 4xx, 5xx, timeout o sin respuesta), Mosce ERP reintenta automáticamente hasta 10 veces en las siguientes 24 horas:

Intento	Tiempo desde el evento original
1 (inmediato)	0 minutos
2	+5 minutos
3	+15 minutos
4	+1 hora
5	+3 horas
6	+6 horas
7	+9 horas
8	+12 horas
9	+18 horas
10	+24 horas

Si el intento 10 también falla, la entrega pasa al estado Agotado (exhausted). El evento no se reintenta más después de esto.

Los reintentos usan el mismo X-Helix-Event-Id que el intento original. Implementa deduplicación por este identificador en tu servidor para procesar el evento exactamente una vez aunque llegue en múltiples intentos. Ver Seguridad y verificación de firma.

Estados de una entrega

Estado	Significado
Pendiente	El evento fue creado y está en cola para el primer intento
En vuelo	Se está procesando el intento actual
Entregado	El servidor respondió con código 2xx
Fallido	El intento actual falló; hay más intentos pendientes
Agotado	Todos los 10 intentos fallaron sin éxito

Auto-deshabilitación por fallos consecutivos

Si 3 entregas consecutivas de eventos distintos llegan al estado Agotado (es decir, los 10 intentos de cada una fallaron), Mosce ERP desactiva automáticamente el endpoint para proteger el rendimiento del sistema.

Cuando esto ocurre:

El webhook aparece en estado "Deshabilitado" en Configuración → Integraciones → Webhooks.
Mosce ERP envía una alerta por correo al proveedor de email configurado en tus integraciones.
Los nuevos eventos no se intentan entregar mientras el endpoint esté deshabilitado.

Cómo rehabilitar el endpoint

Identifica y resuelve el problema en tu servidor receptor (verifica los logs del servidor, asegúrate de que la URL responde con 2xx).
Ve a Configuración → Integraciones → Webhooks y abre el webhook deshabilitado.
Haz clic en Habilitar para reactivarlo.
Usa el botón Probar endpoint para confirmar que la conexión funciona antes de esperar un evento real.

El contador de fallos consecutivos se reinicia a cero cuando el endpoint se rehabilita manualmente o cuando entrega un evento con éxito.

Reenvío manual de una entrega

Si una entrega específica falló o fue agotada y necesitas que tu sistema la procese, puedes reenviarla manualmente:

Ve a Configuración → Integraciones → Webhooks y abre el webhook.
Haz clic en Historial de entregas.
Encuentra la entrega que quieres reenviar (puedes filtrar por estado).
Haz clic en Reenviar en la fila de esa entrega.

El reenvío manual genera un nuevo intento de entrega con el mismo payload y X-Helix-Event-Id que el original. El resultado del reenvío aparece en el historial.

Conteo de entregas y cuota mensual

El límite mensual de entregas de webhooks de tu plan cuenta solo el primer intento de cada evento. Los reintentos automáticos (intentos 2 al 10) y los reenvíos manuales no se contabilizan dos veces - solo el evento original cuenta.

Ver Límites de uso por plan para los límites de entregas de webhooks según tu plan.

Errores comunes

Síntoma	Causa probable	Solución
El webhook se deshabilitó sin que yo hiciera nada	3 entregas consecutivas agotaron sus 10 reintentos	Revisa los logs de tu servidor y rehabilita el endpoint desde la configuración
No recibo el correo de alerta por deshabilitación	El proveedor de email no está configurado	Ve a Configuración → Integraciones → Email y configura tu proveedor de correo
Una entrega aparece como "Entregado" pero mi servidor no la procesó	La firma no fue verificada y el evento fue descartado silenciosamente	Verifica la lógica de verificación en tu servidor - asegúrate de que responde 2xx solo si procesa el evento
Quiero reenviar todos los eventos agotados de la semana	El reenvío es individual por entrega	Usa la API de webhooks para automatizar el reenvío en bulk si tienes muchos eventos pendientes

Preguntas frecuentes

¿Los eventos que llegaron mientras el webhook estaba deshabilitado se reenvían automáticamente al rehabilitarlo?

No. Los eventos generados mientras el endpoint estaba deshabilitado no se encolan retroactivamente - se omiten. Solo los eventos generados después de la rehabilitación se intentan entregar. Para recuperar eventos omitidos, usa el reenvío manual o consulta los datos directamente desde la API de Mosce ERP.