Nouveau : le pare-feu IA surveille toute la plateforme et explique chaque incident en termes simples. Découvrez comment ça marche

Relances de webhooks et idempotence : recevoir des événements sans faire le travail deux fois

Pourquoi les émetteurs relancent, pourquoi une file d'attente et une clé unique sur l'identifiant de livraison évitent le travail en double, et comment tester le gestionnaire avant la mise en production.

Les relances de webhooks et l’idempotence vont de pair. Un émetteur qui ne reçoit pas de réponse 2xx à temps renvoie le même événement, si bien que votre récepteur verra parfois un événement deux fois. Rendez le gestionnaire idempotent : accusez réception rapidement, mettez le travail en file d’attente et enregistrez l’identifiant de chaque livraison afin qu’une répétition soit reconnue et ignorée.

Côté réception d’une intégration, je considère chaque webhook comme un message susceptible d’arriver plus d’une fois. Un gestionnaire qui fait tout le travail pendant la requête finira tôt ou tard par le faire deux fois.

Pourquoi les émetteurs de webhooks renvoient-ils le même événement ?

Un émetteur relance parce qu’il ne peut pas distinguer une requête perdue d’une réponse perdue. Si votre serveur a effectué le travail puis que la connexion a été coupée, ou si votre réponse est arrivée après le délai de l’émetteur, celui-ci enregistre un échec et renvoie l’événement.

RFC 9110, la norme de sémantique HTTP, qualifie d’idempotentes les méthodes PUT, DELETE et les méthodes sûres ; POST n’en fait pas partie. Un client ne devrait pas relancer automatiquement une requête non idempotente, sauf s’il peut savoir qu’elle est idempotente ou détecter que l’original n’a jamais été appliqué. Un émetteur qui relance un POST compte sur le récepteur pour le rendre idempotent, et un identifiant de livraison identique à chaque tentative permet au récepteur de le faire.

Pourquoi utiliser une file d’attente pour les webhooks ?

Une file d’attente permet au gestionnaire de répondre en quelques millisecondes et d’effectuer le travail lent ensuite, de sorte que le délai de l’émetteur n’entre jamais en concurrence avec votre logique métier.

  1. Vérifiez la signature sur le corps brut, si l’émetteur signe ses appels.
  2. Insérez l’identifiant de livraison et le corps brut dans une table dont la clé unique porte sur l’identifiant de livraison.
  3. Répondez 2xx. La RFC 9110 définit 202 Accepted pour ce cas : demande acceptée pour traitement, traitement non terminé.
  4. Un worker lit l’événement stocké, effectue le travail et marque la ligne comme traitée.

Si l’insertion heurte la clé unique, vous avez déjà l’événement : répondez 2xx et ne faites rien d’autre. Une réponse d’erreur à un doublon attire de nouvelles relances. C’est la même idée que la clé unique sur appareil et horodatage dans un module d’écriture de base de données MQTT. Si l’insertion échoue parce que la base de données est indisponible, répondez par une erreur afin que l’émetteur réessaie plus tard.

Que se passe-t-il si un point de terminaison webhook est en panne ?

L’émetteur relance selon son propre calendrier, puis s’arrête. Les tentatives et les délais varient d’un émetteur à l’autre ; lisez donc sa documentation avant de planifier une fenêtre de maintenance.

Les événements relancés arrivent en retard et peuvent arriver dans le désordre ; ordonnez-les donc selon les horodatages du contenu, et non selon l’ordre d’arrivée. Pour une panne longue, conservez une lecture de rattrapage via l’API de l’émetteur, comme dans webhook vs WebSocket vs polling.

Hermetry relie des appareils de terrain à des tableaux de bord, règles et alertes en temps réel : télémétrie IoT et SCADA sur une seule plateforme. Ses webhooks transportent un identifiant X-Webhook-Delivery identique à chaque relance et à chaque renvoi ; les livraisons sont effectuées au moins une fois, sans ordre garanti. Par défaut, une livraison dispose de 3 tentatives, la première comprise, avec des attentes de 60 000 ms et 300 000 ms avant les relances. Après 10 échecs consécutifs, le point de terminaison est désactivé ; lorsqu’un administrateur le réactive, ce qui a échoué peut être livré à nouveau ou rejoué.

Avant d’écrire le worker, consultez la documentation des événements de l’émetteur, par exemple une référence des événements webhook, pour savoir quel champ contient l’heure de l’événement.

Comment tester un webhook sur localhost ?

Un émetteur sur Internet ne peut pas atteindre localhost : rejouez donc d’abord les charges utiles enregistrées sur votre gestionnaire local, puis effectuez un test de bout en bout via une adresse HTTPS publique.

  • Enregistrez une livraison réelle, en-têtes et corps brut, et rejouez-la deux fois avec un client HTTP en ligne de commande. Le second appel doit recevoir un 2xx et ne provoquer aucun effet de bord.
  • Si votre gestionnaire rejette les anciens horodatages, signez les rejeux avec un secret de test et envoyez un horodatage périmé pour vérifier qu’il est refusé.

Un tunnel qui attribue à votre machine une adresse HTTPS publique temporaire couvre le test de bout en bout. Je le ferme lorsque le test réussit.

Questions fréquentes

Un POST de webhook est-il idempotent par défaut ?

Non. La RFC 9110 qualifie d’idempotentes les méthodes PUT, DELETE et les méthodes sûres, et POST n’en fait pas partie. Un POST de webhook ne devient idempotent que si le récepteur le rend tel, par exemple en stockant l’identifiant de livraison sous une clé unique et en ignorant les répétitions.

Combien de temps dois-je conserver les identifiants de livraison ?

Au moins aussi longtemps que l’émetteur peut encore relancer ou renvoyer l’événement ; un renvoi manuel, lorsque l’émetteur en propose un, peut intervenir plusieurs jours plus tard. Chaque identifiant est une courte chaîne : je les conserve pendant des semaines.

Puis-je dédoublonner sur le contenu plutôt que sur un identifiant de livraison ?

Seulement en solution de repli. Deux événements authentiques peuvent avoir un contenu identique, par exemple une valeur franchissant deux fois la même limite. Sans identifiant de livraison, construisez une clé à partir du type d’événement, de l’identifiant de la source et de l’horodatage propre à l’événement.

Partager

Voyez vos données terrain en direct dès cette semaine

Démarrez un essai dans votre région avec vos premiers appareils, ou réservez une démo et apportez votre propre cas d'usage.