Configurer les tentatives de renvoi pour les Webhooks

Dans Dokos, les webhooks permettent d'envoyer des notifications en temps réel à des services externes lorsque certains événements se produisent (par exemple, la création d'une commande client ou la mise à jour d'une facture). Cependant, il arrive que le service externe soit temporairement indisponible, ce qui entraîne l'échec de la livraison du webhook.

Pour améliorer la fiabilité de ces notifications, Dokos propose désormais un mécanisme de tentatives de renvoi automatiques avec un délai progressif (backoff schedule). Cela signifie que si un webhook échoue, Dokos tentera de le renvoyer plusieurs fois à des intervalles croissants avant d'abandonner définitivement.

Fonctionnement des tentatives de renvoi

Processus de renvoi

1. Échec initial : Lorsque Dokos envoie un webhook et que le service externe retourne une erreur (par exemple, un code HTTP 500), le statut du webhook est marqué comme Échoué dans les logs.
2. Première tentative de renvoi : Après 5 minutes, Dokos tente à nouveau d'envoyer le webhook.
3. Tentatives suivantes : Si le webhook échoue à nouveau, les tentatives suivantes sont espacées selon le calendrier suivant :
   • 2ᵉ tentative : 30 minutes après la première tentative.
   • 3ᵉ tentative : 2 heures après la deuxième tentative.
   • 4ᵉ tentative : 5 heures après la troisième tentative.
   • 5ᵉ tentative : 10 heures après la quatrième tentative.
   • 6ᵉ tentative et suivantes : 10 heures après la tentative précédente (jusqu'à épuisement).
4. Épuisement : Si le webhook échoue après 3 tentatives (configurable), son statut passe à Épuisé et aucune autre tentative n'est effectuée.

Conservation du payload

Lors des tentatives de renvoi, Dokos rejoue exactement le même payload que celui qui a été envoyé lors de la première tentative. Cela garantit que le service externe reçoit toujours les données dans l'état où elles étaient au moment de l'événement déclencheur, même si le document a été modifié entre-temps.

Exceptions

• Webhooks de transition de workflow : Ces webhooks continuent de fonctionner de manière synchrone et échouent immédiatement si la livraison n'aboutit pas. Ils ne bénéficient pas du mécanisme de tentatives de renvoi, car la transition de workflow dépend du résultat de la livraison.

Configurer les tentatives de renvoi

Prérequis

• Version de Dokos : Cette fonctionnalité est disponible à partir de la version 16.0.0.
• Permissions : Vous devez avoir les droits d'administrateur pour configurer les webhooks.

Activer les tentatives de renvoi

1. Allez dans Paramètres > Intégrations > Webhook.
2. Sélectionnez un webhook existant ou créez-en un nouveau.
3. Dans la section Paramètres avancés, activez l'option Activer les tentatives de renvoi.
4. Définissez le Nombre maximal de tentatives (par défaut : 3).
5. Enregistrez le webhook.

      
flowchart TD
    A[Événement déclencheur] --> B[Envoi du webhook]
    B --> C{Succès ?}
    C -->|Oui| D[Statut: Livré]
    C -->|Non| E[Statut: Échoué
Tentative 1/3]
    E --> F[Attente 5 min]
    F --> G[Renvoi du webhook]
    G --> C
    E -->|3 échecs| H[Statut: Épuisé]

    

Suivre les tentatives de renvoi

Consulter les logs des webhooks

1. Allez dans Paramètres > Intégrations > Log des requêtes Webhook.
2. Filtrez les logs par statut :
   • Échoué : Le webhook a échoué et sera retenté.
   • En attente de renvoi : Le webhook est en attente de sa prochaine tentative.
   • Épuisé : Le webhook a échoué après le nombre maximal de tentatives.
   • Livré : Le webhook a été envoyé avec succès.

Champs clés dans les logs

Bonnes pratiques

Pour les administrateurs

• Surveiller les logs : Consultez régulièrement les logs des webhooks pour identifier les services externes qui échouent fréquemment.
• Configurer des alertes : Utilisez les notifications par e-mail pour être averti en cas d'échec répété d'un webhook.
• Limiter le nombre de tentatives : Un nombre trop élevé de tentatives peut surcharger votre instance Dokos. Limitez-le à 3 ou 5 selon vos besoins.

Pour les développeurs

• Valider les signatures HMAC : Si votre webhook utilise une signature HMAC pour sécuriser les échanges, Dokos conserve désormais la signature originale sous forme de chaîne de caractères (et non plus sous forme de tableau d'entiers), ce qui garantit sa validité lors des tentatives de renvoi.
• Gérer les erreurs côté serveur : Assurez-vous que votre service externe retourne un code HTTP 200 en cas de succès. Tout autre code (y compris les redirections 3xx) sera considéré comme un échec.

Exemple d'utilisation

Scénario : Notification d'une nouvelle commande client

Contexte : Vous utilisez un webhook pour notifier un système de gestion des stocks externe chaque fois qu'une nouvelle commande client est créée dans Dokos.

1. Création de la commande : Un commercial crée une commande pour le client Maison Verte SARL.
2. Envoi du webhook : Dokos envoie immédiatement un webhook au système de gestion des stocks avec les détails de la commande.
3. Échec temporaire : Le système de gestion des stocks est en maintenance et retourne une erreur HTTP 500.
4. Première tentative de renvoi : Après 5 minutes, Dokos renvoie le webhook.
5. Succès : Le système de gestion des stocks est de nouveau disponible et traite la commande avec succès.

Résultat : Le stock est mis à jour automatiquement, sans intervention manuelle, malgré l'indisponibilité temporaire du système externe.

Dépannage

Problème : Les webhooks ne sont pas retentés

• Vérifiez que l'option est activée : Assurez-vous que l'option Activer les tentatives de renvoi est cochée dans les paramètres du webhook.
• Vérifiez le statut du webhook : Consultez les logs pour confirmer que le webhook a bien été marqué comme Échoué.
• Vérifiez le planificateur : Assurez-vous que le planificateur Dokos est actif et fonctionne correctement.

Problème : Les tentatives de renvoi consomment trop de ressources

• Réduisez le nombre de tentatives : Limitez le Nombre maximal de tentatives à 2 ou 3.
• Désactivez les tentatives pour certains webhooks : Si un webhook n'est pas critique, désactivez les tentatives de renvoi pour éviter de surcharger votre instance.
• Optimisez les intervalles : Si nécessaire, vous pouvez modifier les intervalles de renvoi en personnalisant le code (voir section Personnalisation avancée).

Personnalisation avancée

Modifier les intervalles de renvoi

Les intervalles de renvoi sont définis dans le fichier frappe/integrations/doctype/webhook/webhook.py. Vous pouvez les modifier en créant un hook dans votre application personnalisée :

# hooks.py
def get_webhook_retry_intervals():
    return [
        5 * 60,      # 5 minutes
        30 * 60,     # 30 minutes
        2 * 60 * 60, # 2 heures
        5 * 60 * 60, # 5 heures
        10 * 60 * 60 # 10 heures
    ]

Désactiver les tentatives pour un webhook spécifique

Vous pouvez désactiver les tentatives de renvoi pour un webhook spécifique en utilisant un hook :

# hooks.py
from frappe.integrations.doctype.webhook.webhook import Webhook

def before_webhook_retry(webhook, log):
    if webhook.webhook_doctype == "ToDo" and webhook.webhook_doc_event == "after_insert":
        return False  # Désactive les tentatives pour les webhooks ToDo

Questions fréquentes

Pourquoi mon webhook n'est-il pas retenté ?

Plusieurs raisons peuvent expliquer pourquoi un webhook n'est pas retenté :

• Le webhook est un webhook de transition de workflow (ces webhooks ne bénéficient pas des tentatives de renvoi).
• Le Nombre maximal de tentatives a été atteint.
• L'option Activer les tentatives de renvoi n'est pas cochée dans les paramètres du webhook.
• Le planificateur Dokos n'est pas actif.

Comment savoir si un webhook a été retenté ?

Consultez les logs des requêtes Webhook (Paramètres > Intégrations > Log des requêtes Webhook). Les logs marqués comme En attente de renvoi indiquent que le webhook sera retenté à la date et heure spécifiées dans le champ Prochaine tentative.

Puis-je modifier le payload lors des tentatives de renvoi ?

Non. Pour garantir la cohérence des données, Dokos rejoue toujours le même payload que celui qui a été envoyé lors de la première tentative. Si le document a été modifié entre-temps, ces modifications ne seront pas reflétées dans les tentatives de renvoi.

Comment sécuriser mes webhooks avec HMAC ?

Pour sécuriser vos webhooks avec une signature HMAC :

1. Dans les paramètres du webhook, activez l'option Sécurisé.
2. Définissez une clé secrète (cette clé doit être connue uniquement de Dokos et du service externe).
3. Dans votre service externe, validez la signature HMAC en utilisant la même clé secrète.

Dokos conserve désormais la signature HMAC sous forme de chaîne de caractères, ce qui garantit sa validité lors des tentatives de renvoi.

Que se passe-t-il si le service externe est définitivement indisponible ?

Si le service externe reste indisponible après le Nombre maximal de tentatives, le statut du webhook passe à Épuisé. Aucune autre tentative ne sera effectuée. Vous pouvez alors :

• Corriger l'URL du webhook si elle était incorrecte.
• Contacter le fournisseur du service externe pour résoudre le problème.
• Réessayer manuellement en cliquant sur Renvoyer dans les logs du webhook.