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

Baies de communication et câblage réseau dans un local vide Illustration éditoriale générée par IA

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

  1. 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.

  2. 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.

  3. 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é.

  4. 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.

  5. 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.

  6. 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 fictiveVérification concrèteDé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.

ChampInformation à consigner
ÉvénementFournisseur, compte, identifiant et version
RéceptionSignature validée et horodatage durable
EffetClé métier, état et preuve d’unicité
RepriseCause, 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écanismeUtilitéPoint de vigilance
SignatureVérifier l’origine selon le contratNe rend pas l’effet unique
DédoublonnageReconnaître une notification répétéeVérifier aussi concurrence et effet métier
RapprochementTrouver les absences et écartsSource et période doivent être explicites

Indicateurs de pilotage

IndicateurCe qu’il mesurePremière action
Âge de la fileRetard des événements non terminésExaminer les plus anciens
Effets dupliquésActions métier répétées à tortCorriger l’atomicité
Écarts source / applicationÉtats manquants ou divergentsRapprocher 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é.

Passerelle réseau fictive sans personne, avec fibres ambrées, baie noire et cloison en verre fumé. Illustration éditoriale générée par IA
Passerelle réseau fictive sans personne : fibres ambrées, baie métallique et cloison en verre fumé. Illustration générée, sans lien avec une installation réelle ni preuve de contrôle.

Stripe et GitHub : six différences à ne pas effacer

Stripe et GitHub : six différences à ne pas effacer
Point de contrôleStripeGitHub
En-tête de signatureStripe-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 rejeuLe 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é à suivreevent.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 livraisonEn 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 rapideRetourner 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

Trois identités à conserver séparément
IdentitéExemple fictifUsage et limite
Tentative de transportdelivery_attempt_02Une 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 fournisseurprovider + account + environment + evt_training_001Reconnaî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étiertenant_7 + case_42 + initial_activationEmpê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.

Octets exacts des trois corps
CorpsOctets UTF-8Chaîne exacte, écrite comme une chaîne JSON
A68"{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_42\"}"
B73"{\"id\": \"evt_training_001\", \"type\": \"evidence.ready\", \"object\": \"case_42\"}"
C68"{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_43\"}"
Six empreintes, deux constructions de message
Corps / schémaMessage utiliséHMAC-SHA256 hexadécimal calculé
A · GitHubbodyd6ac0a608c901617782f3b7aef64198718e3affd410a219b22b84da008235364
A · Stripe v1timestamp + "." + body0ad9c9f7c0df2d8a8265113e641d92f57ce0dffd703a7cf9f13c4163e21bf6dc
B · GitHubbodyc9c47b1432282b9a3c2cbf4aded2c750deed235ac948dffe248488b84a4af73d
B · Stripe v1timestamp + "." + body0ad8e262a5870766d4cce864f50a5feac65a3004e3c3208184da9cc075c7abd6
C · GitHubbody55162fc08e3cb0efd0eb082978ba61a88cf3624ffc5322f19ab73d91466a616d
C · Stripe v1timestamp + "." + bodyd7f4014489a900399a7049daa3e8f1ce2b208bf95b93c43492cb68f7d6f1b791

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.

Sept traces pour un seul effet local
Heure UTCSignal observéDécision du scénarioEffets locaux cumulés
10:00:00evt_training_001 admis ; réponse réseau perdueRéception durable, état en attente ; aucun effet métier encore exécuté.0
10:00:01Worker A réclame l’événementRéservation atomique du travail ; état en cours.0
10:00:01Worker B voit le même événementNe pas créer un second propriétaire de traitement ; aucune seconde exécution.0
10:00:02Worker A termine la transaction localeÉcriture atomique de l’activation initiale et de son état terminé.1
10:00:03Nouvelle livraison de evt_training_001Authentifier la nouvelle tentative, retrouver l’événement terminé, acquitter sans second effet.1
10:00:04evt_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:05evt_training_003 porte un état antérieurRefuser 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

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.