Retries et stratégie de backoff
Retries et stratégie de backoff
Gérer les échecs temporaires de livraison des webhooks
Configurer les tentatives de renvoi (retries) et le délai entre tentatives (backoff_seconds) pour rendre vos intégrations robustes face aux erreurs temporaires.
Intro Ce guide explique comment configurer et utiliser les paramètres de renvoi pour les destinations de webhook dans la section “Destinations & Webhooks externes”. Vous apprendrez ce que signifient les paramètres “retries” et “backoff_seconds”, comment DeployIt réagit aux erreurs (codes d’état, timeouts, limites de débit), et quelles stratégies adopter pour rendre vos intégrations résilientes.
En bref
“retries” indique combien de tentatives supplémentaires seront effectuées après la première tentative ; “backoff_seconds” définit le délai de base entre tentatives. DeployIt applique une logique de backoff pour espacer les tentatives et éviter de surcharger les endpoints.
Créer une nouvelle destination de webhook (avec retries/backoff)
Ouvrir le gestionnaire de destinations
Aller dans la rubrique “Destinations” ou “Webhook Destinations” du projet et cliquer sur “Créer une destination” ou le bouton “+”.
Renseigner l'URL et la méthode
Saisir l’URL de réception (endpoint) et choisir la méthode HTTP (POST, PUT, etc.). Vérifier que l’URL est accessible depuis l’environnement de DeployIt (pas d’IP privée bloquée, règles de pare-feu).
Ajouter headers et options d'authentification
Ajouter les en-têtes personnalisés requis (Content-Type, autres) et sélectionner la méthode d’auth (clé API, Basic Auth, signature). Si vous utilisez la signature, renseigner la clé partagée et le format attendu (ex : HMAC + header X-Signature).
Configurer retries et backoff_seconds
- retries : indiquer le nombre de tentatives supplémentaires à effectuer après la première tentative (ex : 3).
- backoff_seconds : indiquer le délai de base avant la première tentative de renvoi (en secondes).
Conseil : choisissez un backoff_seconds raisonnable (p. ex. 5–10 s) et 2–5 retries selon la criticité.
Sauvegarder et tester
Sauvegarder la destination. Utiliser la fonction de test (souvent “Send test” ou “Ping”) pour vérifier la connectivité et visualiser le code de réponse. Si le test échoue, corriger l’URL/headers/auth avant d’activer en production.
Notes sur la sémantique
- La première tentative est immédiate lors d’un événement. Les “retries” s’appliquent si la livraison échoue.
- DeployIt arrête les tentatives dès qu’une réponse indiquant une réussite est reçue (2xx).
- Certaines erreurs (voir section “Quand ne pas relancer”) n’entraînent pas de nouvelle tentative.
Tester en environnement isolé
Créez une destination de test pointant vers un endpoint de staging ou un collecteur d’événements pour vérifier le comportement des retries sans impacter la production.
:::
Modifier les paramètres retries/backoff d'une destination existante
Ouvrir la destination
Dans la liste des destinations, sélectionner la destination à modifier.
Éditer la section retries/backoff
Modifier les champs “Retries” et “Backoff seconds”. Évaluez l’impact (fréquence d’appels, chances de surcharges côté destinataire).
Sauvegarder et valider
Sauvegarder les modifications. Effectuer un envoi de test ou déclencher un hook de test pour observer le comportement réel.
Conserver un historique
Conservez une note (ou nommez les configurations) lorsque vous changez ces paramètres afin de pouvoir revenir en arrière si nécessaire.
:::
Associer une destination à un hook (Trigger)
Ouvrir l'éditeur de hook
Aller dans la gestion des hooks (Agent Hooks) et ouvrir le hook à créer ou modifier.
Sélectionner la destination
Dans la section “Destination” du hook, choisir la destination de webhook précédemment créée dans la liste déroulante.
Configurer filtres et autres options
Si le hook propose des filtres (événements, tags, cadence), configurez-les avant de sauvegarder.
Sauvegarder le hook
Sauvegarder le hook. La prochaine exécution utilisera la configuration de retries/backoff de la destination associée.
:::
Envoyer manuellement un document vers une destination (DialogDocument)
Ouvrir le document
Dans l’interface, ouvrir le document ou l’élément à envoyer.
Choisir la destination
Ouvrir le sélecteur “Destinations” et choisir la destination ciblée. :
Cliquer sur 'Send' ou 'Envoyer'
Lancer l’envoi. L’interface affichera immédiatement le statut initial (succès ou échec). :
Surveiller les logs
Consulter les logs/monitoring pour voir les tentatives : réponse HTTP, codes d’erreur, si les retries ont été déclenchés et à quels intervalles.
:::
Diagnostiquer et résoudre les échecs de livraison
Consulter les logs détaillés
Rechercher l’historique d’envoi de la destination : codes HTTP, messages d’erreur, horodatage des tentatives. :
Identifier le type d'erreur
- 2xx : succès — pas d’action.
- 4xx : erreur client — vérifier payload, auth, URL ; souvent ne pas relancer.
- 429 / 503 / 5xx / timeout : erreurs temporaires — relances appropriées.
:
Ajuster retries/backoff en conséquence
Si vous voyez beaucoup de 429 ou timeouts, augmentez backoff_seconds et ajoutez jitter (voir recommandations). Pour erreurs 4xx, corrigez la requête plutôt que d’augmenter les retries. :
Ajouter une destination de secours
Pour les intégrations critiques, configurez une destination secondaire (fallback) ou activez une route d’alerte (email, Slack) si les retrys échouent. :
Re-tester en masse si nécessaire
Une fois la correction appliquée, renvoyez manuellement les documents échoués (ou attendez la re-déclenchement selon votre flux) et confirmez l’amélioration.
:::
Gotchas fréquents et limites
- Ne confondez pas le nombre total d’envois et “retries” : la première tentative + retries = nombre total d’essais.
- Évitez de configurer un nombre très élevé de retries avec un backoff court : cela peut amplifier la surcharge côté destinataire.
- Les erreurs 4xx (sauf 429) indiquent généralement un problème non transitoire ; relancer inutilement gaspille des ressources.
- Assurez-vous que la clé/secret de signature n’expire pas entre tentatives (décalage horaire, rotation automatique).
Idempotence et déduplication
Si possible, votre endpoint devrait supporter des identifiants d’idempotence (header ou champ dans le payload). Cela permet au récepteur d’ignorer les doublons si une livraison est répétée.
Limiter la taille des payloads pour les retries
Si des échecs sont liés à des limites de taille ou de traitement, envisagez d’envoyer seulement un identifiant puis de permettre au destinataire de récupérer le détail (pull) plutôt qu’un push complet.
- Description : délai initial égal à backoff_seconds, puis multiplier le délai à chaque échec (ex : x2, x4…), en ajoutant un léger jitter aléatoire pour éviter les “thundering herds”.
- Avantages : réduit la pression instantanée sur le endpoint, efficace face aux surcharges et limitations de débit.
- Quand l’utiliser : endpoints partagés, services tiers sujets à throttling, production.
Avantages de l’exponentiel + jitter :
- Réduit les pics de charge.
- Meilleure compatibilité avec les politiques de throttling.
- Diminution des collisions lors de pannes globales.
Inconvénients / limites pratiques :
- Temps total avant abandon peut être long si on multiplie retries et backoff.
- Complexité accrue pour le debug (les tentatives sont espacées).
- Nécessite d’instrumenter le monitoring pour comprendre le comportement.
Frequently Asked Questions
Surveiller et alerter
Instrumentez des alertes sur le taux d’échecs et sur le nombre de retries consommés : un pic indique souvent un problème côté destinataire ou un changement d’API/permission.
Conclusion La configuration de “retries” et “backoff_seconds” est un levier puissant pour améliorer la résilience de vos intégrations webhook. Adoptez une stratégie mesurée (exponentielle + jitter recommandé), testez systématiquement en staging, surveillez les logs et mettez en place des mécanismes d’idempotence et de secours pour réduire les risques de perte ou de surcharge.