Intégrations et événements
Webhooks de réservation : traiter les événements sans doubler une vente
Un paiement, une confirmation fournisseur et une annulation peuvent arriver par des chemins différents. Un événement reçu n’est pas encore un dossier cohérent : il faut l’authentifier, l’enregistrer, le dédupliquer et le rapprocher de l’état réel.
Réponse directe
Un webhook signale un changement, il ne clôt pas le dossier
Une plateforme peut envoyer un événement quand le paiement est confirmé, puis une autre source confirme ou refuse la prestation. Enregistrer immédiatement « voyage confirmé » au premier signal crée une promesse prématurée. Le dossier doit distinguer demande reçue, paiement, confirmation fournisseur, documents émis et notification au voyageur.
La documentation Stripe sur les webhooks décrit la possibilité de livraisons répétées et d’événements reçus hors ordre. La méthode reste valable pour toute intégration événementielle, avec les garanties propres à chaque partenaire.
Séparer accusé de réception et résultat métier
Stripe documente des notifications susceptibles d’être répétées et livrées dans un ordre différent de leur création. Ce comportement est à traiter dans cette intégration ; demandez les garanties propres à chaque autre producteur. Une réponse HTTP réussie à la notification ne signifie pas que le dossier voyage est confirmé.
- Authentifier. Vérifier la signature selon la documentation, avec le corps brut lorsque le mécanisme l’exige.
- Conserver durablement. Enregistrer événement, producteur, compte et identifiant avant d’accuser réception selon le contrat de livraison.
- Dédupliquer. Ne pas répéter l’effet métier d’un événement déjà traité ; deux événements distincts peuvent aussi viser la même opération.
- Rapprocher. Retrouver dossier et état courant auprès de la source ; ne pas régresser vers un état ancien à cause de l’ordre d’arrivée.
- Reprendre. Isoler les échecs, désigner l’équipe responsable et rejouer sans doubler paiement, émission ou message client.
Cas fictif : un remboursement est connu avant que la notification de paiement initiale soit traitée. Le traitement ne doit pas transformer ce dossier en simple « payé ». La preuve attendue réunit les mouvements, l’état de réservation et la prochaine action.
Stripe — livraison, signature, doublons et ordre des événements, consulté le 17/10/2026.
Modéliser les états et les désaccords
| Signal reçu | Contrôle nécessaire | État prudent |
|---|---|---|
| Paiement accepté | Prestation confirmée ? | À rapprocher |
| Réservation fournisseur confirmée | Montant et prestation concordants ? | Confirmée si contrôle passé |
| Annulation demandée | Fournisseur et paiement mis à jour ? | En traitement |
| Remboursement reçu | Montant et dossier associés ? | Rapproché si complet |
Un événement inconnu ou incohérent doit rester observable, sans écraser un état confirmé plus récent. Prévoyez un outil de rejeu et un rapprochement périodique entre le système local et la source.
Une recette avec des événements difficiles
Livrez deux fois la même notification, inversez l’ordre de paiement et de confirmation, coupez la réponse du fournisseur, puis renvoyez un événement ancien après une annulation. Vérifiez le nombre de dossiers, de paiements et de messages envoyés. Aucun rejeu ne doit créer une vente supplémentaire ou effacer l’historique d’une correction.
Une matrice événement → contrôle → transition autorisée, accompagnée d’un journal consultable et d’une procédure de rapprochement.
Suivre les retards et les états orphelins
Comptez les événements reçus, appliqués, ignorés comme doublons et placés en erreur. Alertez sur une file qui vieillit ou sur un paiement sans dossier confirmé. Préservez dans le journal les références utiles au support, mais limitez les données personnelles conservées. Une revue périodique doit comparer les états locaux aux sources externes même lorsque tous les webhooks semblent avoir été reçus.
Rapprocher l’événement avec l’intention initiale
Un événement reçu après une réponse perdue peut compléter la lecture d’état de l’opération. Reliez-le à l’intention et à la référence du fournisseur avant de lancer une nouvelle action. La protection contre les événements répétés et la reprise d’une commande traitent des moments différents du parcours.
La recette inspecte réponses, événements et lectures autorisées sans compter chaque arrivée de message comme une nouvelle vente. Vérifiez le nombre final de réservations, transactions et notifications. Si un mécanisme d’idempotence a une limite de conservation, la reprise tardive doit suivre une procédure qui tient compte de cette limite. Consultez le Réservations et paiements : organiser des reprises sans doublon.
Tester l’ordre documenté plutôt qu’un ordre supposé
Stripe ne garantit pas la livraison des événements dans leur ordre de génération. Sa documentation conseille de suivre les identifiants d’événements pour repérer les doublons. Dans un scénario autorisé de paiement voyage, examinez un état reçu avant un autre et rapprochez-le de l’objet fournisseur. Cette référence décrit Stripe : demandez la règle propre à chaque autre interface. Le test conserve l’état final et l’effet métier, pas seulement le nombre de messages reçus.
Stripe : réception des événements webhook — référence consultée le 10/10/2026 ; portée précisée dans les sources du guide.
Éprouver la même identité chez deux producteurs
Scénario fictif : Deux partenaires transmettent le même identifiant de message. Faites rapprocher leurs sources et leurs dossiers avant de décider qu’un message est déjà traité.
| Point | Preuve | Contrôle proposé |
|---|---|---|
| Contrat à conserver | Source, id et référence métier | Faire préciser ce qui est fourni et ce que le traitement peut conclure. |
| Résultat à rapprocher | Deux événements correctement distingués | Comparer le résultat effectivement observé à celui attendu pour ce cas. |
| Décision de reprise | Une identité isolée ne supprime pas le message d’un autre producteur. | Attribuer la suite et garder l’inconnue visible tant que la preuve manque. |
Une identité isolée ne supprime pas le message d’un autre producteur.
Cadre documentaire : CNCF : CloudEvents, spécification 1.0.2 — référence consultée le . Enveloppe d’événement ; ne garantit ni ordre, livraison unique, authenticité ni état final d’une réservation.
Rapprocher ce sujet du dossier suivant
Un webhook peut être pris en charge par une file avant son effet sur le dossier. La réception HTTP et le résultat du traitement sont alors deux étapes à rapprocher. Conservez identité, tentatives et effet déjà exécuté pour que la reprise d’un message ne déclenche pas une seconde action involontaire.
Files de messages : réception, traitement et reprise des dossiers · Vérifier les preuves de ce dossier
La même notification reçue deux fois
Cas fictif proposé pour préparer vos contrôles ; aucun résultat fournisseur n’est présumé.
Un environnement fictif de recette reçoit deux notifications portant la même référence d’événement. L’équipe veut savoir si le dossier risque d’être traité deux fois.
- Action à préparer
- Rejouer le cas dans un environnement adapté, puis comparer l’identifiant de l’événement, le traitement observé et l’état final du dossier. Contrôler aussi une notification distincte reçue après la première.
- Pièces à rapprocher
- Garder des traces anonymisées des deux réceptions et de l’effet métier constaté. Décrire le résultat attendu avant le test et distinguer l’accusé de réception de la fin du traitement.
- Décision à documenter
- Accepter ce scénario lorsque les répétitions n’entraînent pas d’action métier supplémentaire et qu’un événement distinct reste traité ; sinon documenter la reprise à tester.
Duffel : identifier et vérifier les notifications aériennes
Le guide distingue configuration, contrôle cryptographique et unicité du traitement. Ces trois points ne se remplacent pas mutuellement.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Changement compagnie | order.airline_initiated_change_detected signale un changement initié par la compagnie. | Relire la commande et qualifier les conséquences pour les voyageurs ; la notification ne vaut pas accord du client. |
| Signature | Le contrôle emploie X-Duffel-Signature et un secret ; ce secret n’est montré qu’à la création du webhook. | Prévoir stockage protégé et rotation sans écrire le secret dans les journaux. |
| Doublons | Duffel indique d’utiliser idempotency_key pour l’unicité des événements rejoués. | Ne pas inventer une clé de dédoublonnage à partir de la date de réception. |
| Environnements | Webhooks test et production sont séparés ; live_mode permet de les distinguer. | Ne pas compter un ping de connectivité comme une réservation réelle traitée. |
Comportement décrit par Duffel, à ne pas généraliser aux webhooks de tous les fournisseurs.
Duffel — Receiving webhooks · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Postmark : un code d’erreur peut arrêter les notifications
La réponse du point de réception détermine si Postmark retentera de transmettre un événement sortant.
| Point documenté | Ce que la source précise | Conséquence pour votre contrôle |
|---|---|---|
| Nouvelle tentative | Les erreurs 5xx, 408, 429 et les échecs réseau donnent lieu à des reprises. | Conserver l’événement et surveiller la récupération du service. |
| Arrêt de l’événement | Les autres erreurs 4xx, dont 401, 403, 404 et 422, ne sont pas retentées. | Ne pas compter sur une nouvelle tentative automatique après une erreur d’authentification ou une URL incorrecte. |
| Accusé de réception | Postmark demande une réponse 200 après traitement ou remise à une file durable. | Distinguer réception technique, sauvegarde durable et traitement métier. |
| Vérification | Une défaillance persistante peut suspendre un type d’événement jusqu’à correction et nouvelle vérification. | Contrôler les statuts Delivery et Bounce séparément ; une catégorie qui fonctionne ne prouve pas que l’autre fonctionne. |
| Authentification | Postmark ne fournit pas de signature HMAC ; sa documentation recommande HTTP Basic Authentication en HTTPS et un filtrage des adresses IP. | Contrôler le mécanisme du fournisseur, puis la structure du message, au lieu d’attendre un en-tête de signature inexistant. |
Comportement des webhooks sortants Postmark ; les messages entrants utilisent une infrastructure distincte.
Postmark — Webhooks overview, retry attempts · consultée le . Les contrôles proposés sont une lecture éditoriale de cette référence.
Sources et périmètre des faits documentés
La date de consultation figure avec chaque référence. Les méthodes d’essai et recommandations de ce guide sont éditoriales ; les conditions d’accès et d’usage se vérifient dans la documentation actuelle.
- Stripe — réception des événements : Signature, livraison, doublons et ordre des notifications Stripe ; comportement à vérifier séparément chez chaque autre producteur. (consultée le )
- CNCF : CloudEvents, spécification 1.0.2 : Enveloppe d’événement ; ne garantit ni ordre, livraison unique, authenticité ni état final d’une réservation. (consultée le )
- Duffel — Receiving webhooks : Comportement décrit par Duffel, à ne pas généraliser aux webhooks de tous les fournisseurs. (consultée le )
- Postmark — Webhooks overview, retry attempts : Comportement des webhooks sortants Postmark ; les messages entrants utilisent une infrastructure distincte. (consultée le )
Questions fréquentes
Questions utiles avant de décider
Peut-on créer la réservation à chaque événement de paiement réussi ?
Non. La même notification peut être livrée plusieurs fois. Associez l’événement à une opération identifiée et rendez l’action métier idempotente.
Les événements arrivent-ils toujours dans l’ordre ?
Il ne faut pas le supposer. Le traitement doit savoir retrouver l’état courant auprès de la source et gérer un événement ancien ou manquant.
Que faire si le fournisseur ne répond plus ?
Conservez l’événement, placez le dossier dans un état vérifiable, relancez de façon contrôlée et faites remonter les cas qui exigent une intervention humaine.
Un webhook prouve-t-il qu’aucune autre opération n’existe ?
Il apporte une information sur sa référence. Le rapprochement doit encore contrôler les effets et les dossiers dans chaque système concerné.
Éprouver la même identité chez deux producteurs : quelle preuve conserver ?
Conservez source, id et référence métier, deux événements correctement distingués et la décision attribuée. Une identité isolée ne supprime pas le message d’un autre producteur.
