Dans cet article
Suivre un événement de paiement jusqu’à son effet
Prenons un service fictif d’abonnement. Un prestataire de paiement envoie une notification et l’application doit activer l’accès. La documentation Stripe décrit vérification de signature, livraisons en double et limites d’ordre des événements. Cela rappelle qu’il faut lire le contrat de chaque fournisseur plutôt que supposer qu’une requête HTTP équivaut à une opération métier.
Un chemin proposé vérifie la signature, inscrit l’événement dans une boîte de réception durable et accuse réception après cet enregistrement. Un worker applique ensuite le changement métier. Conservez identifiant, contexte de compte, état de traitement et tentatives. Un accusé positif signifie que l’événement est accepté ; l’outil d’exploitation ne doit pas le présenter comme la preuve que l’abonnement est déjà activé.
Supposer que la livraison est imparfaite
Les webhooks peuvent arriver tard, plusieurs fois ou dans le désordre. Le polling peut manquer un changement bref ou récupérer les mêmes données en boucle. Définissez identité d’événement, version source et règles d’ordre avant de connecter les effets métier.
N’acquittez la livraison entrante qu’après acceptation durable. Conservez la référence fournisseur et les métadonnées contrôlées nécessaires au replay, sans stocker secrets ou données personnelles inutiles.
Rendre les effets idempotents et observables
Utilisez une clé d’idempotence stable pour chaque commande métier et liez-la au payload. Réutiliser une clé avec un contenu différent est un conflit, pas un retry. Des contraintes de base doivent protéger l’invariant en concurrence.
Séparez acceptation et livraison fournisseur avec un outbox lorsqu’un appel externe suit une transaction locale. Suivez les états pending, processing, delivered, retry et dead-letter sans faire attendre l’appelant après un autre vendor.
Un événement répété ne doit pas répéter son effet
Un parcours de livraison illustratif avec état durable.
Recevoir
Valider l’événement entrant et son identité.
Enregistrer
Enregistrer l’acceptation et détecter les répétitions.
Traiter
Appliquer l’effet métier avec une protection contre les doublons.
Réconcilier
Comparer état attendu et état réel après un échec.
Réconcilier, pas seulement réessayer
Les retries résolvent des pannes de transport transitoires, pas les résultats inconnus ou dérives sémantiques. Ajoutez backoff borné, revue dead-letter, replay manuel et réconciliation comparant l’état canonique à celui du fournisseur.
Nommez un responsable pour schémas, credentials, rate limits et breaking changes. Les dashboards doivent montrer quels enregistrements sont en retard, bloqués ou divergents et quelle action sûre les restaure.
Le cas difficile : l’effet a eu lieu, la réponse non
Supposons que le worker active l’accès puis s’arrête avant de marquer l’événement comme terminé. La reprise doit reconnaître l’activation déjà réalisée. Lorsque c’est possible, contrôlez la clé d’opération et le changement local dans la même transaction. Une vérification suivie d’une écriture non protégée ne suffit pas : deux workers peuvent passer le contrôle simultanément.
Si l’effet dépend d’un service distant, une transaction locale ne rend pas cet appel atomique. Utilisez son mécanisme d’idempotence lorsqu’il existe, conservez sa référence d’opération et rapprochez les résultats incertains. Un délai dépassé signifie « inconnu », pas forcément « échoué ». Créez un état à résoudre plutôt que de générer une nouvelle clé et répéter un effet peut-être déjà réalisé.
Accuser réception, puis contrôler l’effet
Chemin de traitement simplifié après vérification de signature. Un résultat distant incertain est rapproché avant une nouvelle tentative.
Vérifier → réception durable → accusé → worker
Opération métier déjà terminée ?
Oui
- Retrouver le résultat enregistré
- Marquer la livraison traitée, sans répéter l’effet
Non
- Réserver la clé → appliquer le changement protégé
- Enregistrer le succès ; rapprocher les résultats incertains
Construire la vue d’incident avant le premier incident
Un opérateur doit retrouver un événement et comprendre s’il a été authentifié, stocké, tenté, terminé ou placé en investigation. Affichez le dernier type d’erreur et la prochaine tentative sans exposer secrets ni charges de paiement complètes. Les actions de rejeu doivent conserver les protections métier habituelles et tracer leur initiateur.
Testez doublon, workers simultanés, ancienne annulation arrivée tard, panne de base et délai dépassé après succès distant. Inspectez ensuite les données métier, pas seulement les codes HTTP. Un rapprochement peut comparer l’état attendu de l’abonnement à l’état faisant autorité chez le fournisseur et signaler les écarts. Cela couvre ce qu’une boucle de tentatives ne peut pas résoudre seule.
Sources et lectures complémentaires
Documentation consultée le .
FAQ / DÉCISIONS
Questions fréquentes
Les webhooks sont-ils toujours meilleurs que le polling ?+
Non. Les webhooks réduisent latence et lectures répétées ; le polling peut simplifier reprise et complétude. Les intégrations critiques utilisent souvent webhooks pour la vitesse et réconciliation périodique.