Temps de lecture estimé : 7 min · Publié le
Écrire le contrat de l’événement
Documentez le producteur, les événements réellement attendus, les champs nécessaires et l’opération déclenchée. Indiquez le résultat attendu pour une création, une modification et une suppression lorsque ces états existent. Une notification ne doit pas être interprétée comme une commande implicite pour toutes les actions possibles.
Choisissez un identifiant de suivi et la source de référence à consulter en cas d’incertitude. Décrivez comment une erreur du producteur ou du destinataire sera constatée. Le dossier d’intégration contient les règles et responsables ; les secrets restent dans le mécanisme sécurisé prévu par le projet.
Dans n8n, les URL de webhook de test et de production ont des usages différents. L’écoute d’un événement de test ne suffit pas à préparer la réception courante : l’URL de production est enregistrée lors de la publication du workflow. Vérifiez l’URL configurée chez l’émetteur et consultez les exécutions de production dans Executions.
Le mode de réponse change le sens de l’accusé de réception. Avec Immediately, la réponse annonce le démarrage du workflow ; elle ne confirme pas que la commande ou la fiche client a été mise à jour. Rapprochez identifiant d’événement, exécution et état final dans le service cible avant d’annoncer une réussite métier.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Point contrôlé | Observation possible | Preuve attendue |
|---|---|---|
| URL de test | Événement visible pendant une écoute de test | URL et environnement utilisés pour l’essai |
| URL de production | Workflow publié et exécution enregistrée | Identifiant d’exécution lié à l’événement reçu |
| Réponse Immediately | Le workflow a démarré | État final et opération attendue dans le service cible |
Vérifier avant de déclencher une action
La documentation GitHub décrit la validation de signature d’une livraison à partir du secret configuré et du contenu reçu. Suivez le mécanisme documenté du fournisseur concerné : les en-têtes, algorithmes et formats ne doivent pas être copiés d’un autre service par analogie.
Séparez validation de l’origine, validation du schéma et autorisation de l’action. Préparez des essais pour un contenu altéré, un type d’événement inattendu et un champ absent. Le traitement métier ne doit démarrer qu’après les contrôles nécessaires au cas d’usage.
Prévoir répétitions et interruptions
Proposez une règle d’idempotence : une même livraison reconnue ne doit pas produire deux commandes ou deux notifications définitives. Testez une répétition avant, pendant et après le traitement, ainsi qu’un arrêt entre deux étapes. Le mécanisme choisi dépend du stockage et de l’opération concernés.
Examinez les garanties d’ordre et de nouvelle livraison du fournisseur au lieu de supposer que tous les événements arrivent immédiatement et une seule fois. Préparez une liste des traitements à vérifier et un moyen de rapprochement avec la source. Une réponse technique positive doit correspondre à un état de traitement défini.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Situation ou réglage | Ce que cela signifie | Vérification utile |
|---|---|---|
| Même événement reçu deux fois | Une seule opération métier doit être appliquée selon la stratégie de déduplication. | Garder l’identifiant d’événement et vérifier l’état final, pas seulement le code HTTP. |
| Événements reçus dans un autre ordre | Reconstituer l’état utile sans supposer l’ordre de livraison. | Tester une mise à jour reçue avant la notification attendue et consulter la source si nécessaire. |
| Signature invalide | Aucun effet métier ne doit être déclenché. | Vérifier le refus, puis la possibilité de traiter un événement valide après cet échec. |
Organiser la surveillance et la reprise
Consignez un identifiant d’événement, un état et une erreur utile en minimisant les données. Définissez qui surveille les échecs, comment relancer un événement autorisé et comment empêcher une relance de dupliquer une opération déjà terminée.
Dans l’environnement d’essai, interrompez le destinataire puis rétablissez-le. Vérifiez le rattrapage et comparez les résultats métier attendus. Le livrable est un contrat d’événement accompagné d’un lot de tests, d’un historique de traitement et d’une procédure de reprise utilisable par l’équipe.
Documentation primaire : GitHub : Validating webhook deliveries.
Exemple fictif : DEMO-E41 déclenche une seule écriture métier dans une base. Le contrat regroupe cette écriture et le marquage de l’événement comme traité dans la même transaction ; une clé unique, associant producteur et identifiant, encadre les traitements concurrents. Testez une interruption avant puis après COMMIT. Une reprise après validation retrouve le traitement effectué, au lieu d’ajouter un second effet. Inscrire « reçu » dans un journal séparé ne fournit pas cette garantie.
Chez GitHub, une relivraison conserve la valeur de X-GitHub-Delivery : une nouvelle tentative ne doit donc pas être considérée comme un nouvel événement sur ce seul motif. Vérifiez ce comportement pour chaque autre producteur. DEMO-E42 illustre une limite différente : un appel à un service externe expire sans réponse. Une transaction locale ne dit pas si ce service a agi ; rapprochez sa référence et les garanties de reprise documentées avant de répéter l’action.
Faites défiler le tableau horizontalement pour lire toutes les colonnes. Au clavier, placez le focus sur le tableau puis utilisez les flèches.
| Cas testé | Effet métier établi | Reprise attendue |
|---|---|---|
| DEMO-E41 avant COMMIT, transaction annulée | 0 effet validé | Reprendre selon le journal transactionnel |
| DEMO-E41 après COMMIT | 1 effet et événement marqué traité | Retrouver le résultat déjà validé |
| DEMO-E41 livré de nouveau | Toujours 1 effet au total | Reconnaître la clé ; ne pas réappliquer l’écriture |
| DEMO-E42 : appel externe sans réponse | Résultat inconnu : 0 ou 1 effet possible | Rapprocher avec le service ; éviter une répétition aveugle |
- GitHub : Webhook Best Practices
GitHub, consulté le 22 octobre 2026 : identifiant conservé lors d’une relivraison. Les événements abrégés DEMO-E41 et DEMO-E42 sont fictifs.
- PostgreSQL : Transactions
PostgreSQL, consulté le 22 octobre 2026 : transaction dans la base ; aucune garantie globale sur un appel externe.
Documents de référence
- Stripe : Webhooks · Source consultée
- n8n : Webhook node · Source consultée
- GitHub : Validating webhook deliveries
Contenu mis à jour le
Repères documentaires pour ce sujet
| Référence | Valeur ou syntaxe | Portée du repère |
|---|---|---|
| RFC 8259 · JSON | application/json · UTF-8 | JSON standard n’autorise ni commentaires ni virgule finale ; les chaînes utilisent des guillemets doubles. |
| RFC 3339 · Date-time | 2026-10-22T09:00:00+02:00 | Le décalage explicite relie l’heure locale à UTC ; cet exemple n’est pas un rendez-vous. |
Les dates indiquent la consultation des références. Ces repères ne constituent ni un audit du site ni une déclaration globale de conformité.
