Comment gérez-vous la réclamation atomique pour les doublons de webhook ?

Pour les récepteurs webhook en production, comment gérez-vous la revendication atomique ?

Une recherche suivie d’une écriture laisse un écart où deux exécutions peuvent toutes deux voir « non vu » avant que l’une ou l’autre n’enregistre « vu ». Dans un lab séquentiel, j’ai utilisé une clé d’événement scoped, mais je n’ai pas prouvé la sécurité concurrente là-bas.

Utilisez-vous une contrainte d’unicité de base de données, des Data Tables, ou un autre stockage pour la revendication — et comment gérez-vous le chemin de conflit ?

@operantsolo

Pour éviter les conditions de concurrence dans les environnements hautement concurrents, vous devriez abandonner la logique « vérifier-puis-agir » (recherche suivie d’une écriture) et utiliser plutôt une stratégie d’insertion atomique. La méthode la plus robuste consiste à utiliser une base de données comme PostgreSQL avec une contrainte UNIQUE sur votre identifiant d’événement. En tentant d’INSERT l’ID d’événement comme toute première étape après la réception du webhook, vous permettez à la base de données de gérer la synchronisation ; si l’insertion échoue en raison d’une violation d’unicité, l’exécution a détecté un doublon et peut être arrêtée ou redirigée en toute sécurité.

Pour les workflows complexes ou de longue durée, vous pouvez étendre cela à un modèle piloté par état pour gérer les défaillances partielles. Au lieu d’une simple vérification d’existence, vous insérez un enregistrement avec un statut comme processing et le mettez à jour à completed uniquement après la réussite du workflow. Cette approche « basée sur l’intention » garantit que si un workflow s’arrête en cours de route, vous pouvez distinguer un événement en cours de traitement, un événement qui a échoué et nécessite une nouvelle tentative, et un événement qui a déjà été entièrement traité.

Bien que n8n fournisse un nœud Remove Duplicates intégré pour la déduplication légère, il n’est généralement pas recommandé pour les webhooks de production critiques car il repose sur l’historique d’exécution interne de n8n et peut ne pas fournir l’atomicité stricte et distribuée requise pour les scénarios hautement concurrents. Pour une fiabilité maximale, l’utilisation d’une base de données externe comme votre « source de vérité » pour l’idempotence via des contraintes uniques reste la norme de l’industrie.

Pour ajouter le côté n8n et le chemin de conflit à l’approche de contrainte unique ci-dessus :

Affirmation. Transformez-le en une seule instruction dans un nœud Postgres (Execute Query), juste après le nœud Webhook :

INSERT INTO webhook_claims (event_key)
VALUES ($1)
ON CONFLICT (event_key) DO NOTHING
RETURNING event_key;

event_key est la clé primaire ou possède une contrainte unique. Passez la clé via les paramètres de requête, pas en construisant la chaîne SQL. Avec ON CONFLICT, un doublon n’est pas une erreur, vous n’avez donc pas besoin de branches d’erreur pour le cas normal.

Chemin de conflit. La première exécution récupère une ligne ; un doublon n’en récupère aucune. Ce que le nœud produit pour « aucune ligne » peut différer selon la version du nœud, testez donc la valeur plutôt que le nombre d’éléments : activez Always Output Data sur le nœud, puis ajoutez un nœud IF qui vérifie que {{ $json.event_key }} existe.

  • Vrai : effectuez le travail.
  • Faux : arrêtez et répondez quand même à l’expéditeur avec un 2xx pour qu’il n’insiste pas.

Blocages. Une affirmation simple bloquera une nouvelle tentative si l’exécution s’arrête après l’affirmation. Si vous avez besoin de nouvelles tentatives, ajoutez les colonnes status et claimed_at et permettez à une affirmation obsolète ou échouée d’être reprise :

INSERT INTO webhook_claims (event_key, status, claimed_at)
VALUES ($1, 'processing', now())
ON CONFLICT (event_key) DO UPDATE
  SET status = 'processing', claimed_at = now()
  WHERE webhook_claims.status = 'failed'
     OR (webhook_claims.status = 'processing'
         AND webhook_claims.claimed_at < now() - interval '15 minutes')
RETURNING event_key;

Définissez l’intervalle plus long que votre exécution la plus lente, et écrivez status = 'done' comme dernière étape.

Tableaux de données. Je ne les ai pas testés sous écritures concurrentes, je ne les utiliserais donc pas pour cela tant que vous n’avez pas exécuté le test ci-dessous.

Pour vérifier : envoyez 20 requêtes parallèles avec la même clé (par exemple curl dans une boucle avec &). Vous devriez voir une ligne dans le tableau et une exécution sur la branche Vrai ; les 19 autres vont à Faux.

Minimolo

En complément de l’approche de contrainte unique : il est utile de stocker un statut avec la ligne de réclamation (par exemple en cours et terminé) plus un horodatage, et pas seulement l’ID d’événement. Un simple drapeau « vu » présente une lacune lorsqu’une exécution réclame un événement et s’arrête ensuite avant de terminer, car la nouvelle tentative sera traitée comme un doublon et l’événement sera perdu.

Avec un statut et un horodatage, vous pouvez laisser une nouvelle tentative reprendre une réclamation qui est en cours de traitement depuis trop longtemps, tout en rejetant les événements qui sont toujours en cours ou déjà terminés.

De plus, l’utilisation d’INSERT … ON CONFLICT DO NOTHING et la vérification du nombre de lignes affectées vous donnent le résultat de la réclamation dans une seule déclaration atomique, donc le chemin de conflit est simplement une branche IF sur ce nombre. Et répondez rapidement à l’expéditeur (par exemple avec le nœud Respond to Webhook) afin qu’il ne réessaie pas pendant que votre flux de travail s’exécute encore.

Une contrainte UNIQUE PostgreSQL est un bon point de départ pour la revendication atomique.

Un cas limite que je testerais est celui où une écriture CRM en aval réussit, mais le workflow plante avant de pouvoir marquer l’événement comme complété. À la nouvelle tentative, l’événement est toujours en « traitement », même si la modification CRM a déjà eu lieu

Pour les intégrations CRM, je préférerais un upsert utilisant un ID externe unique où l’API le supporte, ou réconcilier l’enregistrement cible avant de réessayer tout en se protégeant contre les tentatives concurrentes.

Un bail ou un délai d’expiration peut aider à récupérer les revendications abandonnées, mais il ne rendra pas les appels API en aval idempotents en soi

Tu essaies principalement d’empêcher les écritures en doublon, ou as-tu aussi besoin de récupérer les exécutions partiellement complétées ?

Utilisez une contrainte unique de base de données sur l’ID d’événement et insérez d’abord, au lieu de rechercher puis d’écrire. Si l’insertion réussit, vous possédez l’événement, et si elle échoue avec un conflit, vous arrêtez et retournez 200 pour que l’expéditeur ne réessaie pas. Postgres avec ON CONFLICT DO NOTHING fonctionne bien, et vérifier si une ligne est revenue vous indique le chemin sur lequel vous vous trouvez.

Une lacune dans la route « Remove Items Processed in Previous Executions » concerne la taille de l’historique. Avec « Value Is New », History Size définit le nombre d’éléments que le nœud stocke, avec une valeur par défaut de 10 000. Si le magasin ne conserve que les ID les plus récents, une nouvelle tentative tardive d’un événement ancien semblera nouveau et sera accepté. Dimensionnez donc l’historique en fonction de votre plus longue fenêtre de nouvelle tentative, et non seulement de votre volume quotidien.

La documentation ne décrit pas le comportement en cas d’exécutions concurrentes, donc je ne me fierais pas à ce nœud pour la demande atomique. Une insertion avec une contrainte unique dans Postgres est le modèle plus sûr pour cette partie. Votre fenêtre de nouvelle tentative est-elle plus longue que le nombre d’événements que vous stockez ?