Un transporteur notifie l’expédition d’une commande. L’application enregistre le départ, puis la connexion se coupe avant que le transporteur reçoive l’accusé. Il renvoie le webhook. Plus tard, une notification « en préparation » arrive à son tour. La recette doit prouver que le client ne reçoit qu’un avis de départ et que la commande reste expédiée.
Pour un middleware qui reçoit des webhooks de partenaires, la première décision est de définir ce que garantit l’accusé HTTP. Le récepteur peut confirmer qu’il a mis l’événement à l’abri et traiter son effet métier ensuite. Un journal distinct permet de savoir si le message a été reçu, appliqué, ignoré ou mis en attente.
La méthode consiste à vérifier trois éléments pour une même commande : la trace durable de chaque réception, l’unicité de l’action déclenchée et l’état métier constaté après reprise. Elle aide à diagnostiquer aussi bien une notification perdue qu’une expédition confirmée trop tôt.
Vérifier la réception avant d’accuser le webhook
Authentifier et conserver le message
À la réception, vérifiez la signature sur le corps brut selon les règles de l’émetteur. Appliquez aussi la fenêtre de validité prévue par son contrat lorsqu’elle existe. Identifiez le compte et l’environnement de provenance avant de partager un même registre entre plusieurs partenaires. Conservez l’identifiant fourni, la ressource métier, le type d’événement, la date de réception et la version du contrat. Protégez le contenu brut par des droits et une durée de conservation proportionnés au besoin de reprise.
Le récepteur écrit dans un registre durable ou une file durable avant de répondre avec le statut de succès attendu. Si l’écriture échoue, il laisse à l’émetteur la possibilité d’appliquer sa politique de nouvelle tentative. Enregistrez l’événement et rendez-le disponible pour le traitement dans une même opération durable, ou prévoyez un processus qui reprend automatiquement les réceptions enregistrées mais encore en attente de traitement.
Examinez les règles du fournisseur sur l’accusé, la redélivrance et l’ordre. Stripe, par exemple, documente les doublons possibles, la vérification des signatures sur le corps brut et une livraison qui peut arriver dans le désordre. Documentation des webhooks Stripe.
Séparer l’accusé HTTP de l’effet sur la commande
Une réception réussie signifie que le récepteur peut retrouver l’événement même si le consommateur s’arrête. Le suivi du traitement indique si la commande a avancé. Affichez au support l’état du traitement, le motif et l’action permise. Une panne temporaire de l’ERP peut déclencher une nouvelle tentative. Une référence de commande inconnue peut demander une correction de correspondance ou une vérification côté émetteur.
Identifier la livraison du message et l’action métier
Protégez deux opérations. L’identifiant d’événement, dans le périmètre où l’émetteur le garantit unique, permet de reconnaître sa redélivrance. Une clé métier, par exemple l’identifiant d’expédition associé à l’action « notifier le départ », protège l’effet si deux événements distincts décrivent le même départ. Pour un effet externe, vérifiez l’idempotence offerte par le service appelé ou rapprochez son résultat après une réponse perdue avant de relancer.
Une commande peut partir en deux colis. Une clé fondée sur le seul numéro de commande absorberait le second avis légitime. En revanche, la même clé d’action pour deux réceptions relatives au même colis doit produire un seul avis. Faites figurer les deux cas dans la recette.
Classer une notification arrivée en retard
Si le contrat fournit une version fiable de la ressource, comparez-la avec la dernière version traitée. Sinon, faites appliquer les transitions autorisées par le métier. Une commande expédiée reste expédiée quand un ancien avis la dit en préparation. Une annulation peut être une transition légitime selon le parcours. Quand ni la version ni la transition ne suffisent, consultez l’état confirmé auprès du partenaire avant de rejouer.
Dans un scénario fictif, le transporteur envoie l’expédition EXP-481 sous l’événement evt-81. Une panne coupe la réponse après l’enregistrement. Le partenaire renvoie evt-81, puis l’ancien evt-76 portant l’état « en préparation ». Le registre rattache la redélivrance à la première réception et classe evt-76 comme obsolète. La recette vérifie un seul avis de départ, la commande toujours expédiée et un motif de classement pour chaque réception.
Tester une réponse perdue et un rejet métier
- Coupez le récepteur juste après la mise en file et avant la réponse HTTP. Le partenaire renvoie l’événement et le support retrouve une seule réception à traiter.
- Coupez le consommateur après la mise à jour de la commande et avant qu’il marque le traitement terminé. À la reprise, vérifiez l’unicité de l’effet et le résultat enregistré.
- Envoyez une référence inconnue après un accusé réussi. L’événement doit rester visible dans la file de traitement avec son motif et un responsable.
- Inversez l’ordre de deux notifications et introduisez une signature invalide. Vérifiez séparément l’état final de la commande et le refus d’entrée du message invalide.
Mesurer le délai jusqu’à l’effet métier
Suivez l’âge de la plus ancienne notification en attente et le délai entre réception et effet confirmé. Comparez aussi le nombre d’expéditions chez le transporteur avec le nombre de notifications reçues. Une file vide peut coïncider avec un arrêt des envois. L’écart donne au support une liste de commandes à rapprocher.
Fixez les seuils selon le délai promis au client et la capacité du support. Si un incident bloque les avis d’expédition, distinguez les commandes effectivement parties de celles encore en préparation avant de relancer une série d’envois.
Préparer une procédure de rejeu et de retour arrière
La procédure demande l’identifiant de réception et la référence de commande. Elle affiche l’état déjà confirmé, la version du contrat et la dernière tentative. Avant le rejeu, l’opérateur vérifie si l’effet a déjà eu lieu. Il choisit l’action permise et consigne le résultat. Pour un retour arrière, suspendez le traitement concerné en conservant les messages reçus. Reprenez après rapprochement avec les dossiers déjà traités.
Répartir les décisions entre intégration et support
L’intégration tient le contrat, les secrets et les règles de classement. Le métier décide quelles transitions sont permises. Le support peut relancer un traitement récupérable et transmettre un écart à la personne qui peut le trancher. Faites jouer la reprise par une personne qui connaît la commande et dispose uniquement des droits utilisés en production.
Repérer les causes qui faussent la reprise
Trois erreurs reviennent dans la recette. Une clé recalculée à chaque tentative masque une redélivrance. Une comparaison sur la seule heure d’arrivée peut faire reculer le dossier. Une file d’échecs vidée après la correction supprime le lien entre le message reçu et la décision prise.
Choisir entre rejeu, correction et rapprochement
Rejouez une erreur transitoire lorsque l’effet reste identifiable. Corrigez la référence ou le contrat quand la validation a échoué. Rapprochez l’état avec la source quand la réponse a été perdue ou que les messages se contredisent. Classez l’événement comme obsolète lorsque la règle métier permet de l’expliquer et que l’état final est confirmé.
Vérifier un remboursement reçu avant la confirmation de paiement
Dans un autre cas fictif, le système reçoit le remboursement de la transaction PAY-304 alors que la confirmation du paiement initial n’est pas arrivée. Le support retrouve la transaction auprès du prestataire et contrôle le montant remboursé. Si le remboursement intégral est confirmé, l’arrivée tardive de l’événement de paiement complète la chronologie sans rouvrir la préparation. Un remboursement partiel déclenche le contrôle prévu sur les lignes concernées. La recette rapproche les montants, l’état de la commande et les écritures conservées.
Valider un premier webhook de bout en bout
- Choisissez un événement et une action. Documentez le point d’accusé, les clés d’unicité et les transitions autorisées.
- Pour chaque dossier pilote, notez l’état attendu, le nombre d’effets autorisés et la trace que le support doit retrouver.
- Exécutez les scénarios de retard, de redélivrance et de panne. Mettez en pause les nouveaux dossiers si un effet se répète ou si un événement accusé ne peut plus être retrouvé.
- Élargissez lorsque le support sait reconstituer la chronologie et que le rapprochement confirme l’effet attendu pour chaque dossier du pilote.
Poursuivre selon la frontière à fiabiliser
Pour coordonner paiement, stock et expédition après réception, utilisez le guide d’orchestration des flux métier. Quand l’application doit publier sa propre décision après écriture en base, le guide sur l’outbox transactionnelle et la reprise du relais traite la frontière d’émission.
Si une même demande peut provoquer deux effets, approfondissez la conception d’une clé d’idempotence et la reprise sur erreur.
Conclusion : vérifier la notification et son résultat
Un webhook exploitable se retrouve dans le registre dès que le récepteur l’accuse. Le support peut ensuite expliquer les redélivrances, la décision du consommateur et l’effet vu par le client. Le premier contrôle utile est de prendre une notification accusée et de suivre son parcours jusqu’à la commande, au stock ou au paiement.
Dawap peut auditer la réception et la reprise dans votre middleware sur mesure. Prenons un incident existant et construisons la recette qui démontrera que la correction tient après une réponse perdue et une redélivrance.