API et automatisation

Webhooks reçus dans le désordre : éviter qu’un ancien événement ne rétablisse l’état d’un fichier

L’heure de réception ne suffit pas à établir l’ordre des changements. Découvrez comment vérifier le contrat du webhook et réconcilier l’état du fichier selon des critères vérifiables.

Apification
Schéma de notifications de fichier reçues dans un ordre différent et d’une application qui réconcilie son état

La réception ne prouve pas l’ordre des changements

Un webhook peut informer votre application d’un événement asynchrone. Toutefois, l’heure de réception par votre serveur ne permet pas à elle seule de déterminer quand le changement a eu lieu ni lequel de deux changements est antérieur. Si chaque notification remplace simplement l’enregistrement local, une vue obsolète peut donc être rétablie.

Les références générales expliquent différents usages des webhooks, mais ne définissent pas le contrat d’ordre de votre intégration. [Stripe](https://docs.stripe.com/webhooks?locale=es-ES) les présente comme un moyen de réagir à des événements asynchrones ; [Microsoft Learn](https://learn.microsoft.com/es-es/sharepoint/dev/embedded/build/respond-to-changes-webhooks) recommande les webhooks Microsoft Graph pour réagir à des changements de fichiers dans SharePoint Embedded ; [Shopify](https://help.shopify.com/es/manual/fulfillment/setup/notifications/webhooks) décrit leur usage pour récupérer et stocker les données d’un événement. Ces trois pages sont en espagnol. Pour définir comment comparer ou réconcilier les événements, consultez la documentation technique du fournisseur concerné.

Les méthodes proposées ici sont des modèles de conception généraux, pas des garanties de livraison, d’ordre ou de cohérence. Distinguez l’heure du changement, l’heure d’émission de l’événement et l’heure de réception. Ne comparez des champs que si le fournisseur documente leur signification et leur portée.

  • Notez la signification de chaque champ temporel et le périmètre dans lequel il peut être comparé.
  • Utilisez l’heure de réception locale pour l’observabilité, pas comme preuve de causalité.
La réception ne prouve pas l’ordre des changements

Modélisez une réception dans le désordre

Supposons que « budget.docx » soit renommé « budget-final.docx », puis déplacé dans un dossier d’approbation. Si la notification du déplacement est traitée avant celle du renommage, appliquer chaque message comme s’il décrivait à lui seul l’état définitif risque de rétablir un nom ou un emplacement obsolète.

Avant l’implémentation, représentez l’état initial, les changements réels, les notifications émises, leur ordre de traitement et le résultat local attendu. Vérifiez aussi si chaque notification décrit un changement partiel ou contient un état complet : cette distinction détermine comment la traiter.

  • Testez le cas où le changement A a lieu avant B, mais où sa notification est traitée après celle de B.
  • Vérifiez que l’enregistrement local ne revient pas à un état antérieur à cause de l’ordre de traitement.
Modélisez une réception dans le désordre

Vérifiez le contrat avant de comparer les événements

Cherchez dans la documentation un champ de séquence, de version ou d’heure que le fournisseur définit expressément comme comparable. Confirmez sa signification, sa portée, le traitement des valeurs manquantes et la possibilité qu’il soit réinitialisé. Un nom comme « updated_at » ou « version » ne suffit pas à établir que deux notifications peuvent être ordonnées.

Si le fournisseur documente une séquence monotone applicable au fichier, vous pouvez l’utiliser comme critère d’acceptation : enregistrez la dernière valeur acceptée avec l’état local et comparez chaque notification selon les règles documentées. Protégez la comparaison et l’écriture par une opération atomique. Définissez aussi le traitement des valeurs identiques, manquantes ou invalides.

  • Documentez le champ, sa sémantique, sa portée de comparaison et le traitement des valeurs impossibles à comparer.
  • Une mise à jour atomique protège l’enregistrement contre les écritures concurrentes ; elle ne prouve pas que tous les événements ont été reçus.

Sans critère d’ordre fiable, envisagez une lecture de réconciliation

En l’absence de champ d’ordre documenté, un modèle de conception possible consiste à traiter le webhook comme une notification indiquant que le fichier a peut-être changé, puis à consulter la ressource via l’API, si le fournisseur propose cette opération. Vérifiez que vous pouvez identifier le fichier et que la réponse contient les champs nécessaires.

Une réponse de l’API ne garantit pas, à elle seule, que vous lisez l’état distant le plus récent. Consultez la documentation du fournisseur pour connaître les garanties de cohérence et l’effet éventuel des caches. Si ces garanties ne sont pas documentées, considérez la lecture comme une source d’information utile, et non comme une preuve d’actualité.

Si la lecture échoue ou ne permet pas d’identifier la ressource, conservez l’état local existant et appliquez une politique de nouvelles tentatives adaptée à votre système. Distinguez une erreur temporaire d’une confirmation que le fichier n’existe plus.

  • Vérifiez l’opération de lecture, l’identifiant requis, les champs renvoyés et les garanties de cohérence documentées.
  • Ne transformez pas un échec de lecture en suppression ni en mise à jour confirmée.

Protégez l’écriture locale contre les réponses concurrentes

Deux notifications peuvent déclencher des lectures simultanées. Si la première prend plus de temps et que sa réponse est enregistrée après celle de la seconde, elle peut remplacer un résultat déjà écrit. L’ordre de fin des requêtes ne permet pas, à lui seul, de déterminer quelle réponse reflète les données distantes les plus récentes.

Vous pouvez sérialiser les réconciliations par fichier ou attribuer à chaque requête un numéro de génération local, vérifié au moment de l’enregistrement. Ce numéro peut empêcher une tâche locale plus ancienne de remplacer le résultat d’une tâche plus récente, mais il ne permet pas de savoir quelle réponse contient les données distantes les plus récentes. Pour cela, les garanties documentées de l’API restent nécessaires. Vous pouvez aussi regrouper les notifications et lancer une consultation après une série rapprochée, si la latence qui en résulte est acceptable.

  • Testez des réponses de l’API qui se terminent dans l’ordre inverse de leur démarrage.
  • Distinguez la protection contre les écritures locales obsolètes de la garantie d’actualité des données distantes.

Testez les répétitions, les permutations et les échecs

Exécutez le même ensemble de changements avec des notifications dans l’ordre normal, dans l’ordre inverse et selon d’autres permutations. Incluez des notifications répétées : la déduplication est liée au problème, mais reste distincte de l’ordre. Vérifiez l’état final attendu, pas seulement le code de réponse du récepteur.

Variez les cas : renommer et déplacer, modifier l’emplacement et l’état, renommer deux fois, et combiner des champs issus de notifications partielles. Ajoutez des échecs de lecture de l’API et deux processus concurrents. Si vous travaillez avec des fichiers versionnés, vous pouvez comparer l’enregistrement local à l’historique disponible ; ne supposez pas que cet historique remplace un contrat d’ordre.

  • Critère d’acceptation : les permutations testées ne font pas revenir l’enregistrement en arrière par rapport à l’état vérifié selon les garanties disponibles.
  • Consignez séparément les échecs de livraison, de lecture et de mise à jour locale.

Consignez les informations utiles au diagnostic

Consignez une référence non sensible au fichier, le type d’événement, les champs d’ordre documentés s’il y en a, l’heure de réception, le résultat de la lecture de l’API et la décision concernant l’écriture locale. Un identifiant de corrélation propre à votre système peut aider à suivre la notification jusqu’à la réconciliation. Évitez d’enregistrer des jetons, des secrets ou le contenu complet du fichier, et limitez les données personnelles au strict nécessaire.

Des journaux qui distinguent la réception, la lecture, la comparaison et l’écriture facilitent le diagnostic d’une divergence. Apification propose une intégration via REST API et webhooks ; ses fonctions d’automatisation comprennent les nouvelles tentatives, l’historique et les statistiques. Consultez la documentation applicable pour confirmer les informations disponibles dans votre flux : ces fonctions aident à observer une intégration, mais ne définissent pas de critère d’ordre.

  • Séparer la réception, la lecture, la comparaison et l’écriture aide à localiser le point de divergence.
  • N’incluez ni identifiants sensibles ni secrets dans les journaux.

Questions fréquentes

Puis-je ordonner les événements selon l’heure à laquelle mon serveur les reçoit ?

Non, pas pour établir quel changement a eu lieu en premier. N’utilisez un champ d’ordre que si le fournisseur en documente la signification et la portée.

Une lecture de l’API renvoie-t-elle toujours l’état le plus récent ?

Pas nécessairement. Vérifiez dans la documentation les garanties de cohérence et l’effet éventuel des caches. Sans ces informations, ne considérez pas une réponse comme une preuve d’actualité.

Que faire si le webhook ne contient pas de champ de séquence ?

Si l’API propose une lecture adaptée et documente la manière d’identifier la ressource, vous pouvez traiter le webhook comme une notification déclenchant une réconciliation. Vérifiez aussi les garanties de cette lecture.

La plateforme Apification garantit-elle que les webhooks de fichiers arrivent dans l’ordre ?

Les informations produit disponibles confirment l’intégration via REST API et webhooks, ainsi que les nouvelles tentatives, l’historique et les statistiques pour les automatisations. Elles ne précisent pas de garantie d’ordre pour les événements de fichiers ; vérifiez la documentation applicable avant de vous y fier.

Sources et lectures

Documentation consultée pour préparer cet article.

Découvrez Apification

Articles associés

Retour au blog