Pourquoi mon endpoint de webhook a-t-il été désactivé ?

Cet article explique pourquoi Emailit cesse d’envoyer des événements à un webhook, comment trouver l’erreur sous-jacente et comment récupérer les événements manqués.

Symptômes

• Vous avez reçu un e-mail d’Emailit indiquant que votre webhook échoue, puis un autre indiquant qu’il a été désactivé.
• Le webhook apparaît comme désactivé dans Email API›Webhooks, et les nouveaux événements n’atteignent plus votre endpoint.
• L’onglet Requests de la page du webhook liste des requêtes au statut Failed avec de nombreuses tentatives.

Cause

Emailit considère toute réponse 2xx comme un succès. Tout le reste compte comme un échec, notamment :

• Les codes de statut 4xx ou 5xx, provenant par exemple de vérifications de signature ou de plantages.
• L’absence de réponse sous 30 secondes.
• Les redirections. Emailit ne suit pas les 301 ni les 302 : une URL http:// qui redirige vers https://, ou une barre oblique finale manquante, échoue donc à chaque fois.
• Les erreurs DNS, de certificat TLS ou de connexion.

Les requêtes en échec font l’objet de nouvelles tentatives après 5 minutes, 30 minutes, 2 heures et 5 heures, puis toutes les 12 heures, dans la limite de 11 tentatives. Emailit envoie un e-mail au propriétaire de l’espace de travail lorsqu’une requête échoue pour la troisième fois. Si l’endpoint continue d’échouer sans aucune livraison réussie pendant 3 jours, le webhook est désactivé et le propriétaire reçoit un nouvel e-mail.

Tant qu’un webhook est désactivé, les nouveaux événements ne sont pas mis en file d’attente pour lui.

Solution

1. Trouvez l’erreur. Ouvrez le webhook et sélectionnez l’onglet Requests. Ouvrez une requête en échec pour voir la Failure reason, le Status code et le corps de réponse renvoyé par votre endpoint.

2. Corrigez l’endpoint. Corrections fréquentes :

   • Utilisez l’URL finale, avec https:// et le chemin exact, pour éviter toute redirection.
   • Renvoyez 200 rapidement et effectuez les traitements lents dans une tâche en arrière-plan, pour rester sous 30 secondes.
   • Corrigez la vérification de signature. Consultez Pourquoi la signature de mon webhook ne correspond-elle pas ?.
   • Laissez passer les requêtes d’Emailit dans votre pare-feu, votre WAF ou votre protection anti-bots.

3. Testez-le. Choisissez Send test, sélectionnez un type d’événement et vérifiez que la boîte de dialogue affiche un statut 2xx.

4. Réactivez et renvoyez. Choisissez Retry failed. Cette action remet en file d’attente toutes les requêtes en échec des 7 derniers jours et réactive le webhook. Vous pouvez aussi sélectionner Enable webhook, ou appeler Relancer les requêtes en échec.

5. Récupérez les événements de la période de désactivation. Les événements créés pendant que le webhook était désactivé n’ont pas été mis en file d’attente. Récupérez-les avec Lister les événements, en filtrant par type et created_at.

Pour rendre votre gestionnaire robuste, rendez-le idempotent grâce au champ event_id, car un lot relancé peut arriver deux fois. Consultez Nouvelles tentatives et échecs.

Le problème persiste ?

Contactez le support ou posez votre question sur Discord en indiquant l’ID du webhook (wh_…) et le motif d’échec affiché dans l’onglet Requests.