Ressources · 54
Webhooks : traiter les répétitions, retards et reprises
Passer d’une notification reçue à un effet métier unique, traçable et récupérable après une panne.
· 3 min
Ce que ce guide permet
- Authentifier la notification
- Séparer réception et traitement
- Éviter l’effet en double
- Reprendre les événements bloqués
Contrôle express
- Quel octet est signé ?
- Quand la réception devient-elle durable ?
- Deux workers peuvent-ils agir ensemble ?
- L’ordre est-il garanti par le fournisseur ?
- Comment retrouver un événement perdu ?
Méthode pas à pas
- 01
Lire le contrat fournisseur
Documentez types, version, contexte de compte, signature, délais et politique de répétition. Stripe indique que l’ordre de livraison n’est pas garanti et que des doublons sont possibles ; ne généralisez pas un délai Stripe à toutes les API.
Livrable : contrat daté par fournisseur.
- 02
Valider avant tout effet
Vérifiez signature selon la bibliothèque et le corps brut requis par le fournisseur. Limitez taille et types acceptés. Testez signature invalide et contexte de compte inattendu dans un environnement autorisé, sans journaliser de secret.
Livrable : refus et absence d’effet.
- 03
Enregistrer avant d’acquitter
Séparez réception durable et traitement lent. Si la file n’accepte pas l’événement, ne répondez pas comme s’il était conservé. Une réponse de succès signifie réception selon votre contrat, pas nécessairement achèvement du métier.
Livrable : états reçu, en cours, terminé et bloqué.
- 04
Contrôler l’idempotence
Définissez une clé d’événement et l’identité de l’effet métier. Testez les répétitions concurrentes, pas seulement séquentielles. Une vérification préalable sans verrou ou contrainte atomique peut laisser deux traitements produire le même effet.
Livrable : preuve d’unicité de l’effet.
- 05
Gérer retard et désordre
Ne supposez pas qu’une notification ancienne décrit l’état courant. Reconsultez la source lorsque le contrat le permet et appliquez des transitions métier validées. Conservez les événements que vous ne pouvez pas encore interpréter.
Livrable : transitions et tests inversés.
- 06
Rapprocher et rejouer
Préparez une file d’échec avec propriétaire, cause, tentative et clôture. Rejouez en conservant la protection contre doublons. Rapprochez périodiquement source et application : une reprise réussie ne prouve pas qu’aucun événement n’a manqué.
Livrable : procédure de reprise et rapport d’écarts.
Fiche de travail à réutiliser
À compléter avec vos observations autorisées. Ces champs constituent une trame de travail, pas des résultats observés.
| Champ | Information à consigner |
|---|---|
| Événement | Fournisseur, compte, identifiant et version |
| Réception | Signature validée et horodatage durable |
| Effet | Clé métier, état et preuve d’unicité |
| Reprise | Cause, tentative, responsable et clôture |
Exemple d’application
Situation illustrative
Exemple fictif : deux workers reçoivent la même notification de confirmation pendant une reprise.
Décision et preuve attendue
La contrainte d’unicité de l’effet et l’état transactionnel permettent une seule préparation ; les deux réceptions restent traçables.
Distinguer les mécanismes
| Mécanisme | Utilité | Point de vigilance |
|---|---|---|
| Signature | Vérifier l’origine selon le contrat | Ne rend pas l’effet unique |
| Dédoublonnage | Reconnaître une notification répétée | Vérifier aussi concurrence et effet métier |
| Rapprochement | Trouver les absences et écarts | Source et période doivent être explicites |
Indicateurs de pilotage
| Indicateur | Ce qu’il mesure | Première action |
|---|---|---|
| Âge de la file | Retard des événements non terminés | Examiner les plus anciens |
| Effets dupliqués | Actions métier répétées à tort | Corriger l’atomicité |
| Écarts source / application | États manquants ou divergents | Rapprocher et clore avec preuve |
Erreurs fréquentes
- Parser avant la vérification du corps signé
- Acquitter avant réception durable
- Supposer une livraison ordonnée
- Tester les doublons uniquement l’un après l’autre
Questions fréquentes
Un succès HTTP signifie-t-il traitement terminé ?
Cela dépend du contrat. Dans un traitement asynchrone, il doit signifier que la réception est durable, tandis que l’état métier reste suivi séparément.
Peut-on compter sur une livraison exactement une fois ?
Concevez le traitement pour répétitions et pannes selon le contrat réel, avec unicité de l’effet et rapprochement.
Faut-il conserver le corps complet ?
Seulement si nécessaire, avec accès et durée adaptés. La trace minimale doit permettre diagnostic et reprise sans conserver des secrets.
Références officielles
Références consultées le 2 octobre 2026. La méthode et la fiche de travail proposent des contrôles à adapter à votre contexte ; elles ne constituent pas une certification.
Pour aller plus loin
Analyses associées
