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.
· 11 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.
Quatre situations pour éprouver la méthode
Cas pédagogiques fictifs. Chaque situation relie un signal à une vérification et à une décision limitée par les preuves ; aucun résultat client n’est représenté.
| Situation fictive | Vérification concrète | Décision et limite |
|---|---|---|
| Un événement de paiement répété ne doit pas doubler l’effet — La même notification de paiement arrive deux fois ; le traitement tente deux activations du même abonnement. | Vérifier l’authenticité de l’événement, reconnaître les répétitions et rapprocher l’état de la facture et de l’abonnement avec la source autorisée. | Confirmer un effet métier unique et journaliser la répétition sans recopier de secrets. Un accusé HTTP ne prouve pas à lui seul une activation correcte. |
| Séparer la demande d’envoi et sa livraison — Une API accepte une demande de SMS ; le tableau interne l’affiche immédiatement comme livrée avant le retour du statut de livraison. | Conserver les identifiants et distinguer accepté, en attente, échec et livré selon les événements réellement reçus. Tester une notification retardée ou répétée. | Afficher l’état connu avec son heure et traiter les cas incertains. Une requête acceptée ne constitue pas une preuve de réception par la personne. |
| Une désinscription doit résister aux événements tardifs — Une personne se désinscrit, puis une synchronisation ancienne remet son profil dans un segment destiné à une campagne. | Tester l’ordre inversé des mises à jour, la répétition d’un événement et le contrôle de la préférence juste avant l’envoi autorisé. | Définir une règle de résolution et une source de préférence fiable. Le succès d’une synchronisation ne démontre pas la justesse de l’éligibilité à l’envoi. |
| Rejouer un workflow à partir de l’étape échouée — Un scénario crée une fiche, puis échoue lors de la notification. Une relance complète crée une seconde fiche. | Identifier les effets de chaque étape, les clés permettant de reconnaître une opération existante et le point de reprise après un échec partiel. | Rejouer sans répéter l’effet déjà confirmé ou prévoir une compensation contrôlée. Une automatisation doit expliciter ses états intermédiaires. |
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.
Idempotence et contrats de reprise API
Distinguer reprise de requête et répétition de notification
La clé d’une requête envoyée à une API, l’identifiant d’une notification reçue et l’identité de l’effet métier ne remplissent pas le même rôle.
- Définir fournisseur, compte, événement et effet avant de choisir une clé de dédoublonnage.
- Tester deux workers concurrents et un résultat d’effet externe inconnu.
- Rapprocher l’état métier avec la source ; une signature valide ne rend pas le traitement unique.
Comparer les contrats d’idempotence →
Références relues le · RFC 9110 · §9.2.2, §10.2.3 · RFC 6585 · §4 · Stripe
Webhooks : signatures et rejeu
Authentifier une livraison, conserver l’événement et maîtriser son effet
La signature d’un webhook répond à une question précise : les octets reçus correspondent-ils à ceux authentifiés avec la clé attendue ? Elle ne garantit ni la fraîcheur de la notification, ni son unicité, ni la réussite d’une action métier. Séparez ces décisions dans le contrat de réception pour rendre l’intégration observable et récupérable.
Les règles de signature et de reprise ci-dessous sont propres aux contrats Stripe et GitHub cités. La chronologie et les dix cas sont des exercices fictifs ; aucun endpoint, secret réel ou mécanisme de paiement n’est activé par cette page. Pour une intégration réelle, utilisez les bibliothèques officielles et testez la configuration du fournisseur concerné.
Stripe et GitHub : six différences à ne pas effacer
| Point de contrôle | Stripe | GitHub |
|---|---|---|
| En-tête de signature | Stripe-Signature contient t et une ou plusieurs signatures v1. Le schéma actif documenté est v1. | X-Hub-Signature-256 porte un HMAC-SHA256 préfixé par sha256=. |
| Message authentifié | Concaténation du timestamp texte, d’un point et du corps brut : timestamp + "." + body. | Corps brut de la livraison. Les en-têtes de transport ne sont pas ajoutés à ce message HMAC. |
| Fraîcheur et rejeu | Le timestamp est authentifié. La documentation annonce une tolérance par défaut de cinq minutes dans ses bibliothèques ; une nouvelle tentative reçoit un nouveau timestamp et une nouvelle signature. | Le HMAC du corps ne contient pas, à lui seul, une preuve de fraîcheur comparable au timestamp Stripe. Prévoir le contrôle des répétitions et la reprise selon le contrat. |
| Identité à suivre | event.id reconnaît une notification répétée. Stripe signale aussi des événements distincts pouvant nécessiter un rapprochement par data.object.id et event.type. | X-GitHub-Delivery identifie la livraison ; une relivraison demandée conserve cet identifiant. Sa valeur reste extérieure au corps authentifié par le HMAC décrit ici. |
| Échec de livraison | En mode live, reprises automatiques pendant au plus trois jours avec backoff exponentiel. Un renvoi manuel n’annule pas automatiquement cette reprise. | GitHub ne relivre pas automatiquement les échecs. Organiser une relivraison manuelle ou un processus de reprise développé pour les API disponibles. |
| Acquittement rapide | Retourner rapidement un 2xx avant les traitements longs. La réception durable avant acquittement est la règle d’architecture retenue dans notre exercice. | Répondre en 2xx dans les dix secondes selon la documentation. La mise en file permet de séparer réception et traitement métier. |
Trois identités à conserver séparément
| Identité | Exemple fictif | Usage et limite |
|---|---|---|
| Tentative de transport | delivery_attempt_02 | Une même notification peut être livrée plusieurs fois. Le timestamp et la signature d’une tentative ne constituent pas une clé métier. |
| Événement fournisseur | provider + account + environment + evt_training_001 | Reconnaître le même événement dans son périmètre. Fixer durée de conservation et comportement des reprises ; un identifiant isolé sans contexte peut être insuffisant. |
| Effet métier | tenant_7 + case_42 + initial_activation | Empêcher ici une seconde activation initiale. Cette clé est propre à cette opération ; ne pas supprimer toutes les futures mises à jour d’un objet en les ramenant à son seul identifiant. |
Trois corps, six HMAC : l’effet d’un simple reformatage
Clé publique réservée à l’exercice : training-only-key-not-a-secret. Timestamp fixe : 1792663200, soit le 22 octobre 2026 à 10:00:00 UTC. Chaque chaîne est encodée en UTF-8 sans saut de ligne final. A et B représentent le même objet JSON mais pas les mêmes octets ; C modifie case_42 en case_43.
| Corps | Octets UTF-8 | Chaîne exacte, écrite comme une chaîne JSON |
|---|---|---|
| A | 68 | "{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_42\"}" |
| B | 73 | "{\"id\": \"evt_training_001\", \"type\": \"evidence.ready\", \"object\": \"case_42\"}" |
| C | 68 | "{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_43\"}" |
| Corps / schéma | Message utilisé | HMAC-SHA256 hexadécimal calculé |
|---|---|---|
| A · GitHub | body | d6ac0a608c901617782f3b7aef64198718e3affd410a219b22b84da008235364 |
| A · Stripe v1 | timestamp + "." + body | 0ad9c9f7c0df2d8a8265113e641d92f57ce0dffd703a7cf9f13c4163e21bf6dc |
| B · GitHub | body | c9c47b1432282b9a3c2cbf4aded2c750deed235ac948dffe248488b84a4af73d |
| B · Stripe v1 | timestamp + "." + body | 0ad8e262a5870766d4cce864f50a5feac65a3004e3c3208184da9cc075c7abd6 |
| C · GitHub | body | 55162fc08e3cb0efd0eb082978ba61a88cf3624ffc5322f19ab73d91466a616d |
| C · Stripe v1 | timestamp + "." + body | d7f4014489a900399a7049daa3e8f1ce2b208bf95b93c43492cb68f7d6f1b791 |
Ces résultats utilisent les constructions de message documentées, avec une clé publiquement affichée et des données inventées. Ce ne sont pas des livraisons Stripe ou GitHub authentiques. Une sérialisation JSON différente, même sémantiquement équivalente, ne doit pas être substituée au corps original avant vérification. En production, comparer en temps constant et gérer la rotation des clés selon la bibliothèque et le contrat retenus.
Attention au paramètre de tolérance Stripe : la valeur 0 désactive le contrôle de fraîcheur dans les bibliothèques décrites par la documentation. Elle ne signifie pas « accepter uniquement la seconde exacte ». Ne pas transposer la politique d’horloge de l’exemple OAuth/OIDC à ce paramètre.
Sept traces pour un seul effet local
Scénario fictif au 22 octobre 2026, heures UTC. La notification est authentifiée avant admission ; sa réception est durable avant réponse. Une contrainte atomique protège l’activation initiale dans la même base que son état métier. Les nombres ci-dessous sont calculés pour cet exercice et ne décrivent aucun résultat client.
| Heure UTC | Signal observé | Décision du scénario | Effets locaux cumulés |
|---|---|---|---|
| 10:00:00 | evt_training_001 admis ; réponse réseau perdue | Réception durable, état en attente ; aucun effet métier encore exécuté. | 0 |
| 10:00:01 | Worker A réclame l’événement | Réservation atomique du travail ; état en cours. | 0 |
| 10:00:01 | Worker B voit le même événement | Ne pas créer un second propriétaire de traitement ; aucune seconde exécution. | 0 |
| 10:00:02 | Worker A termine la transaction locale | Écriture atomique de l’activation initiale et de son état terminé. | 1 |
| 10:00:03 | Nouvelle livraison de evt_training_001 | Authentifier la nouvelle tentative, retrouver l’événement terminé, acquitter sans second effet. | 1 |
| 10:00:04 | evt_training_002 vise la même activation initiale | Événement distinct conservé ; la clé de cette opération métier existe déjà. | 1 |
| 10:00:05 | evt_training_003 porte un état antérieur | Refuser une transition régressive selon la politique de l’exercice et rapprocher la source. | 1 |
La transaction décrite protège un effet local. Elle ne rend pas atomique un appel à un service externe. Après un résultat externe inconnu, conserver l’incertitude, vérifier la source et appliquer le mécanisme d’idempotence disponible avant toute relance. Une boîte d’envoi transactionnelle peut organiser l’émission ; elle ne crée pas une garantie universelle « exactement une fois ».
Dix tests de refus et de reprise à préparer
01 · Signature invalide : aucun effet
Présenter une livraison dont le HMAC ne correspond pas au corps reçu.
Attendu : refus avant admission et avant effet. Conserver un motif expurgé et la version de configuration ; ne pas enregistrer la clé, le jeton ou des données sensibles du corps.
02 · JSON reformaté avec la signature d’origine
Remplacer A par B tout en conservant la signature calculée pour A. Les deux JSON se décodent vers le même objet.
Attendu : échec de vérification. Capturer le corps brut à la bonne étape du framework ; ne pas chercher à retrouver la signature en testant des reformattages.
03 · Signature correcte, timestamp trop ancien
Dans un test Stripe, authentifier un timestamp de 09:50:00 alors que l’horloge de recette vaut 10:00:00, avec une tolérance configurée de cinq minutes.
Attendu : refus de fraîcheur malgré un HMAC correct. Distinguer intégrité du message, âge de livraison et âge de création de l’événement.
04 · Même événement, nouvelle tentative authentifiée
Recevoir deux livraisons du même event.id ; la nouvelle tentative Stripe porte son propre timestamp et sa propre signature.
Attendu : authentifier chaque tentative puis retrouver l’état durable. La signature différente ne justifie pas un second effet métier.
05 · Deux événements, une activation initiale
Recevoir deux identifiants d’événement distincts qui demandent la même activation initiale fictive de case_42.
Attendu : tracer les deux événements et protéger cette opération avec sa clé métier. Cette règle ne s’applique pas aveuglément aux mises à jour successives légitimes du même objet.
06 · Deux workers au même instant
Déclencher deux workers sur le même élément en attente dans l’environnement de recette autorisé.
Attendu : une acquisition atomique et une seule transaction d’effet. Une séquence « lire absent, puis insérer » sans contrainte peut laisser passer les deux workers ; inspecter le résultat métier, pas seulement les logs.
07 · File indisponible avant acquittement
Simuler une file ou une base indisponible avant que la réception soit confirmée durablement.
Attendu dans notre architecture : ne pas acquitter comme si l’événement était conservé. Exercer la stratégie de reprise propre au fournisseur ; GitHub n’assure pas de relivraison automatique des échecs.
08 · Réponse perdue après réception durable
Couper la réponse après persistance de la notification ; laisser le traitement poursuivre selon la politique de l’exercice.
Attendu : la tentative suivante retrouve l’état en attente, en cours ou terminé. Le client distant peut ignorer la réception réussie ; cette incertitude réseau ne doit pas doubler l’effet.
09 · Événement ancien reçu après un état récent
Livrer une notification portant un état antérieur après une notification plus récente.
Attendu : appliquer les transitions métier autorisées et rapprocher l’état courant si nécessaire. Un timestamp de signature récent peut transporter un événement ancien ; il ne prouve pas la nouveauté de l’état métier.
10 · Reprise manuelle et retry automatique simultanés
Faire converger une reprise manuelle et une reprise automatique Stripe vers le même événement.
Attendu : mêmes protections de concurrence et d’idempotence pour les deux chemins. Un renvoi manuel réussi n’annule pas de lui-même les retries automatiques ; suivre la clôture avec le fournisseur.
Six preuves utiles à l’exploitation
- Contrat daté par fournisseur : environnement, compte, type, version, signature, délais et reprise.
- Trace d’admission expurgée : identifiant interne, résultat de vérification, horloge et version de la politique.
- État durable de l’événement, propriétaire du travail et preuve de la contrainte d’unicité testée.
- Identité de l’effet et liste des opérations légitimement répétables ; distinguer événement et objet métier.
- File d’échec avec cause, nombre de tentatives, responsable, prochaine action et clôture vérifiée.
- Rapprochement source/application sur une période définie, y compris notifications jamais reçues et effets externes incertains.
Contrats fournisseurs et sources primaires
- Stripe · Webhooks · Living documentation · reviewed 2026-10-22
Event delivery behaviors · Handle duplicate events · Verify manually · Preventing replay attacks - Stripe · Manage webhook endpoints · Living documentation · reviewed 2026-10-22
Process undelivered events · Resolve signature verification errors - GitHub · Validating webhook deliveries · Living documentation · reviewed 2026-10-22
HMAC-SHA256 · X-Hub-Signature-256 · raw payload · constant-time comparison - GitHub · Best practices for using webhooks · Living documentation · reviewed 2026-10-22
Respond within 10 seconds · X-GitHub-Delivery · redelivery retains the identifier - GitHub · Handling failed webhook deliveries · Living documentation · reviewed 2026-10-22
No automatic redelivery · manual or application-managed recovery
Sources vérifiées le
Erreurs API : types, statuts et preuves
Une réponse d’erreur ne garantit ni l’échec ni le rejeu sans risque
Après une interruption ou une réponse incohérente, un appel peut avoir produit un effet. Problem Details améliore la description ; il ne prouve pas l’absence de traitement et ne fournit pas une politique universelle de relance.
- Conserver statut HTTP, corps reçu et identifiant de l’opération autorisé dans les traces.
- Vérifier l’état métier et les règles d’idempotence avant de répéter une action.
- Tester les messages publics sans exposer secrets, chemins internes ou détails de compte.
Explorer les types de problèmes et les huit réponses fictives →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5
Références officielles
Date de consultation des références : . La méthode et la fiche de travail proposent des contrôles à adapter à votre contexte ; elles ne constituent pas une certification.
- Stripe — Webhooks
- Stripe — Process undelivered webhook events
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457
- IETF · RFC 9110 — Retry-After et idempotence HTTP
- IETF · RFC 6585 — 429 Too Many Requests
- AWS Builders’ Library · Timeouts, retries, and backoff with jitter
- Stripe · Idempotent requests
- Stripe · API v2 overview — Idempotency
- Stripe · Advanced error handling
