Rédaction : 4SYSTEMPublié le Mis à jour le

7 min de lecture

Comment distinguer réception et traitement métier, résister aux doublons et reprendre les événements après une panne sans répéter les actions.

Pour fiabiliser des webhooks e-commerce, vérifiez la signature, enregistrez durablement la livraison avant de confirmer sa réception et exécutez les actions avec une protection contre les doublons. Un webhook est une notification envoyée à votre application ; sa réception ne prouve pas que la commande a été traitée. Shopify documente les livraisons répétées, et Stripe précise que l’ordre d’arrivée des événements n’est pas garanti.[1][3] Concevez donc le circuit pour supporter une répétition, un retard et une interruption.

Distinguer livraison, événement et action métier

La livraison est la requête reçue. L’événement est ce qui s’est produit sur la plateforme. L’action métier est ce que votre système décide d’en faire : mettre à jour un état, créer une préparation ou transmettre une demande. Ces identités ne se confondent pas. Dans Shopify, la documentation distingue X-Shopify-Webhook-Id pour dédoublonner les livraisons et X-Shopify-Event-Id pour corréler plusieurs livraisons provenant d’une même action du marchand.[1]

Définissez aussi le système qui fait autorité pour chaque donnée. Une notification ancienne ne doit pas écraser aveuglément un état plus récent. Selon le besoin, le traitement peut relire l’objet courant auprès de la plateforme et décider si l’action reste pertinente. Les identifiants, la portée du compte et la version du format doivent figurer dans le contrat d’intégration. Cette précision est plus utile qu’une promesse générale d’automatisation marketing.

Attribuer une responsabilité à chaque étape

Une architecture lisible sépare l’accueil rapide de la requête et le travail susceptible de durer. Shopify recommande la mise en file pour absorber les pics ; Stripe recommande également un traitement asynchrone.[1][3] La grille suivante décrit des responsabilités de conception, pas une garantie fournie automatiquement par une bibliothèque.

Responsabilités du circuit de réception
Étape du webhookResponsabilitéTrace technique à conserver
Réception d’un webhookVérifier l’origine et le format attenduRésultat de validation et identifiant
EnregistrementConserver une tâche durable et son étatIdentifiant de tâche et date de réception
TraitementAppliquer une action sans effet répétéClé métier et résultat de l’opération
Reprise après incidentRéexaminer les tâches incomplètesHistorique des tentatives et motif d’échec

Construire une réception et un traitement séparés

La signature doit être vérifiée sur le corps brut, avant qu’une transformation ne le modifie. Shopify et Stripe le précisent dans leurs documentations respectives.[1][3] Utilisez les outils officiels adaptés à votre environnement et gardez les secrets hors des journaux. Une signature valide ne dispense pas du contrôle des doublons ni des règles métier.

  1. Recevoir la requête, préserver le corps brut et vérifier la signature selon le contrat exact du fournisseur. Rejeter une validation invalide sans lancer d’action métier.
  2. Construire une identité persistante incluant le fournisseur, le compte concerné et l’identifiant de livraison ou d’événement approprié.
  3. Enregistrer la tâche avec une contrainte d’unicité. Une simple recherche suivie d’une insertion séparée laisse une course possible entre requêtes concurrentes.
  4. Confirmer la réception seulement après cet enregistrement durable. Si le stockage échoue, ne pas prétendre avoir accepté une tâche qui pourrait être perdue.
  5. Faire traiter la tâche par un exécutant distinct, avec états explicites, réservation du travail et protection de l’action métier contre une répétition.
  6. Conserver le résultat et prévoir la reprise des tâches échouées ou abandonnées, sans réexécuter indistinctement toutes les actions réussies.

Le dédoublonnage d’une livraison ne suffit pas si le processus tombe après l’action externe mais avant son enregistrement local. Pour ce cas, prévoyez une clé d’idempotence acceptée par le système destinataire ou une vérification de l’effet déjà produit. L’idempotence signifie ici qu’une répétition ne crée pas un effet métier supplémentaire. Une transaction locale ne peut pas, à elle seule, englober une action distante indépendante.

Exemple fictif : une préparation créée une seule fois

Exemple entièrement fictif : un événement nommé evt-demo concerne la commande CMD-DEMO. L’application reçoit une livraison, la conserve et crée une tâche de préparation. Une nouvelle livraison arrive après une coupure réseau. Le circuit reconnaît l’identité déjà conservée et ne crée pas une nouvelle tâche métier. Il peut confirmer la réception parce que le travail initial reste durablement suivi, même s’il n’est pas encore terminé.

Si l’outil logistique a accepté la préparation avant une panne de l’exécutant, la reprise vérifie la clé métier associée à CMD-DEMO au lieu d’envoyer une nouvelle création sans contrôle. Les états doivent permettre de distinguer « reçu », « en cours », « réussi » et « à reprendre ». Cet exemple n’affirme aucun comportement d’une application réelle : chaque système destinataire doit être qualifié pour cette protection.

Préparer les incidents et le rapprochement

Les nouvelles tentatives du fournisseur ne remplacent pas votre procédure de récupération. Shopify explique comment réimporter les données manquantes après une indisponibilité et vérifier les abonnements concernés.[2] Définissez une fenêtre de rapprochement, les données à relire, les autorisations de reprise et le contrôle final. Une notification de vente ne doit pas devenir automatiquement une preuve de revenu dans votre plan de mesure des événements.

  • Prévoir un essai de livraisons identiques et concurrentes : une seule action métier attendue.
  • Prévoir une interruption après stockage, puis après action externe, afin de vérifier les deux chemins de reprise.
  • Prévoir des événements retardés ou désordonnés et contrôler que l’état final reste cohérent avec la source.
  • Suivre l’âge des tâches, les échecs et les résultats du rapprochement, avec des journaux limités aux données nécessaires.

Questions fréquentes

Une réponse de succès signifie-t-elle que tout est terminé ?

Non. Elle peut signifier que la notification a été acceptée durablement pour traitement. L’état métier doit être suivi séparément. Cette distinction permet une réception rapide sans affirmer que l’opération logistique ou comptable a déjà abouti. Documentez précisément ce que votre réponse engage.

Peut-on utiliser le même identifiant partout ?

Non sans vérifier sa portée. Un identifiant peut désigner une livraison, un événement ou un objet métier. Shopify distingue notamment ses identifiants de livraison et de corrélation d’événement. Le choix dépend de l’effet à protéger et du périmètre de l’intégration, pas seulement du nom de l’en-tête.[1]

La file garantit-elle un traitement exactement une fois ?

Ne le supposez pas. Le circuit doit supporter une reprise et protéger l’effet final, y compris après une panne entre deux systèmes. Vérifiez séparément le stockage, la concurrence et l’idempotence du destinataire. Une réception sans erreur ne démontre pas cette propriété de bout en bout.

Décrire les garanties avant de connecter les outils

Des webhooks e-commerce fiables demandent une identité claire, un stockage durable et des actions vérifiables après incident. Commencez par le scénario dont une répétition serait coûteuse, puis définissez ses preuves de réception et de réussite. Pour cadrer les échanges entre boutique et outils métier, les prestations de 4SYSTEM permettent de discuter du contrat d’intégration et de la recette, sans présenter un exemple pédagogique comme un connecteur universel.

Sources

  1. Verify webhook deliveries
  2. Troubleshoot webhooks
  3. Recevez les événements Stripe dans votre endpoint de webhook

FR