Traitement idempotent des webhooks : identifiants de livraison, calendriers de nouvelles tentatives et réponse rapide

Ce que c'est

Chaque fournisseur désigne un champ servant au dédoublonnage, mais le comportement de nouvelle tentative qui l'accompagne n'est pas interchangeable. L'identifiant de livraison de GitHub (X-GitHub-Delivery) identifie une livraison, et "if you request a redelivery, the X-GitHub-Delivery header will be the same as in the original delivery." La documentation de GitHub indique aussi sans détour : "GitHub does not automatically redeliver failed webhook deliveries, but you can handle failed deliveries manually or by writing code". Un récepteur qui rate une livraison (y compris toute réponse plus lente que 10 secondes) doit donc le détecter et déclencher une nouvelle livraison via l'interface ou l'API REST, laquelle ne couvre que les livraisons récentes (les pages de GitHub mentionnent actuellement à la fois 3 et 7 jours). Stripe fait l'inverse : son guide des webhooks avertit que "webhook endpoints might occasionally receive the same event more than once", recommande de journaliser les identifiants d'événements traités (et, dans le cas rare de deux objets Event distincts, de dédoublonner sur l'id de data.object combiné à event.type), et documente des nouvelles tentatives automatiques "for up to three days with an exponential back off in live mode" (trois nouvelles tentatives sur quelques heures dans un sandbox) ; les renvois manuels fonctionnent jusqu'à 15 jours depuis le Dashboard et 30 jours via la CLI. L'Events API de Slack réessaie "a failed request up to 3 times in a gradually increasing timetable" : presque immédiatement, puis après 1 minute, puis après 5 minutes. Chaque tentative est marquée par un en-tête x-slack-retry-num (1, 2 ou 3) et un en-tête x-slack-retry-reason qui en donne la cause (http_timeout, http_error, etc.) ; une réponse non 2xx portant x-slack-no-retry: 1 interrompt les tentatives suivantes. La spécification Standard Webhooks recommande précisément ce schéma de façon générique : "Use the webhook-id header as an idempotency key to prevent accidentally processing the same webhook more than once (e.g. save the IDs in redis for 5 minutes)."

Pourquoi c'est important

Traiter deux fois le même événement peut entraîner un double débit, une double notification ou une double modification d'état. Une politique de nouvelle tentative que l'on ignore (ou une politique supposée exister alors qu'elle n'existe pas) provoque soit des effets de bord en double, soit la perte silencieuse d'événements.

Comment l'appliquer

• Conserver les identifiants traités (identifiant de livraison, identifiant d'événement ou webhook-id) avec une durée d'expiration au moins égale à la fenêtre de nouvelle livraison du fournisseur : au moins 7 jours pour GitHub, 3 jours pour les tentatives automatiques de Stripe (jusqu'à 30 jours si quelqu'un renvoie manuellement), et plus que la durée d'environ six minutes des tentatives pour Slack.
• Acquitter rapidement (2xx sous 10 secondes pour GitHub, sous 3 secondes pour Slack, "quickly" pour Stripe) et exécuter les traitements à effets de bord après l'acquittement, dans une file d'attente, afin qu'un appel aval lent ne provoque pas un timeout côté fournisseur qui déclencherait une nouvelle tentative indésirable.
• Pour GitHub en particulier, ne pas supposer qu'une livraison manquée ou en échec arrivera de nouveau d'elle-même ; mettre en place une surveillance ou une récupération planifiée des livraisons récentes.
• Enregistrer dans les logs l'en-tête indiquant la cause de la nouvelle tentative, lorsque le fournisseur en propose un (comme Slack) : il permet de savoir si la tentative vient du récepteur ou du réseau.

Pièges

Dédoublonner sur un hash du payload plutôt que sur l'identifiant du fournisseur : des payloads peuvent légitimement se répéter (deux transactions identiques de faible montant), alors que les identifiants, eux, ne se répètent jamais. Supposer que la fenêtre de nouvelle tentative de Stripe ou de Slack est assez courte pour qu'un cache de dédoublonnage en mémoire, propre à chaque processus, suffise : un redémarrage entre deux tentatives fait perdre l'enregistrement.