¿Por qué se ha desactivado mi endpoint de webhook?

Este artículo explica por qué Emailit deja de enviar eventos a un webhook, cómo encontrar el error de fondo y cómo recuperar los eventos que te perdiste.

Síntomas

• Recibiste un email de Emailit que decía que tu webhook estaba fallando y, más tarde, otro que decía que se había desactivado.
• El webhook aparece como desactivado en Email API›Webhooks, y los eventos nuevos ya no llegan a tu endpoint.
• La pestaña Requests de la página del webhook lista peticiones con el estado Failed y muchos intentos.

Causa

Emailit considera correcta cualquier respuesta 2xx. Todo lo demás cuenta como fallo, incluido lo siguiente:

• Los códigos de estado 4xx o 5xx, por ejemplo por comprobaciones de firma o por errores de la aplicación.
• La ausencia de respuesta en 30 segundos.
• Las redirecciones. Emailit no sigue 301 ni 302, así que una URL http:// que redirige a https://, o a la que le falta la barra final, falla siempre.
• Los errores de DNS, de certificado TLS o de conexión.

Las peticiones fallidas se reintentan a los 5 minutos, 30 minutos, 2 horas y 5 horas, y después cada 12 horas, hasta 11 intentos. Emailit envía un email al propietario del espacio de trabajo cuando una petición falla por tercera vez. Si el endpoint sigue fallando sin ninguna entrega correcta durante 3 días, el webhook se desactiva y el propietario recibe otro email.

Mientras un webhook está desactivado, los eventos nuevos no se ponen en cola para él.

Solución

1. Encuentra el error. Abre el webhook y selecciona la pestaña Requests. Abre una petición fallida para ver el Failure reason, el Status code y el cuerpo de la respuesta que devolvió tu endpoint.

2. Corrige el endpoint. Soluciones habituales:

   • Usa la URL final, con https:// y la ruta exacta, para que no haya ninguna redirección.
   • Devuelve 200 rápidamente y haz el trabajo lento en una tarea en segundo plano, para no superar los 30 segundos.
   • Corrige la verificación de la firma. Consulta ¿Por qué no coincide la firma de mi webhook?.
   • Permite el paso de las peticiones de Emailit en tu firewall, tu WAF o tu protección contra bots.

3. Pruébalo. Elige Send test, selecciona un tipo de evento y confirma que el cuadro de diálogo muestra un estado 2xx.

4. Reactívalo y vuelve a enviar. Elige Retry failed. Vuelve a poner en cola todas las peticiones fallidas de los últimos 7 días y reactiva el webhook. También puedes seleccionar Enable webhook o llamar a Reintentar las peticiones fallidas.

5. Recupera los eventos del periodo en que estuvo desactivado. Los eventos creados mientras el webhook estaba desactivado no se pusieron en cola. Obtenlos con Listar eventos, filtrando por type y created_at.

Para que tu gestor sea robusto, hazlo idempotente con el campo event_id, porque un lote reintentado puede llegar dos veces. Consulta Reintentos y fallos.

¿Sigues teniendo problemas?

Contacta con soporte o pregunta en Discord indicando el ID del webhook (wh_…) y el motivo del fallo de la pestaña Requests.