Interroger l’état de l’activation est la manière la plus simple d’obtenir un code : vous envoyez une requête, vous regardez la réponse et, si elle est vide, vous recommencez quelques secondes plus tard. Cette simplicité est trompeuse : chaque requête superflue pèse sur la limite de l’API, et le délai reste de toute façon aléatoire, car le code peut apparaître juste après une vérification et attendre jusqu’au cycle suivant. Le webhook fonctionne autrement : le serveur vous signale lui-même l’événement à l’instant où il se produit. Voyons ce que le passage au webhook change en pratique, ce qu’il faut préparer de votre côté, comment distinguer un véritable appel d’une contrefaçon et dans quels cas le polling reste incontournable.
Push contre interrogation : ce que le webhook apporte
Avec le polling, le client sollicite le point de terminaison de statut toutes les quelques secondes, et jusqu’à la réception du code, presque toutes les réponses signifient « rien de nouveau ». Avec une dizaine d’activations en parallèle, cela fait déjà des centaines d’appels inutiles par minute, qui butent sur la limite de l’API sans pour autant supprimer le délai entre l’apparition du code sur le serveur et le moment où l’application en est informée. Ce qu’est un code, l’article qu’est-ce qu’un code OTP l’explique en détail.
Le webhook inverse le schéma : le serveur de l’expéditeur déclenche lui-même une requête vers l’adresse du webhook dès que l’événement est prêt. Le délai se réduit au temps d’acheminement d’une seule requête HTTP, et le nombre d’appels à l’API tombe à un par activation, au lieu de dizaines d’interrogations en attendant le résultat.
Ce qu’il faut préparer de votre côté
La première exigence est une adresse de webhook accessible publiquement. Le récepteur doit répondre depuis l’extérieur en HTTPS : avec un nom de domaine ou une adresse IP publique, sans adresse de réseau local et sans proxy entre l’expéditeur et votre serveur. Si l’adresse ne se résout pas depuis Internet, l’événement n’a nulle part où être livré : l’expéditeur enregistrera une erreur de connexion, et non un simple silence de son côté. Les raisons pour lesquelles un récepteur devient injoignable sont détaillées dans l’article sur la rupture des rappels.
La deuxième exigence est la rapidité de réponse. Le gestionnaire du webhook doit accepter le corps de la requête et renvoyer aussitôt un code 2xx, sans attendre la logique métier : analyse du texte, recherche du code par expression régulière, écriture en base. Ce travail part dans une file d’attente et s’exécute dans un processus distinct. Si vous traitez tout de manière synchrone avant de répondre, un ralentissement de la base ou d’un service tiers se soldera par un délai d’attente dépassé, et l’expéditeur considérera la livraison comme un échec, alors que l’événement est bel et bien arrivé.
Signature de la requête : comment vérifier qu’un webhook est authentique
L’adresse publique d’un webhook est visible par quiconque la trouve ou la repère dans du trafic intercepté. Sans contrôle d’authenticité, le point de terminaison acceptera n’importe quel corps au contenu arbitraire : il suffit d’envoyer une requête POST avec un « code » inventé pour que le gestionnaire l’avale comme un véritable événement.
La signature comble cette faille : l’expéditeur calcule l’empreinte du corps de la requête avec une clé secrète et place le résultat dans un en-tête ; le récepteur recalcule l’empreinte avec la même clé et compare les valeurs. La concordance confirme à la fois l’authenticité de la source du webhook et le fait que le corps n’a pas été modifié en chemin. La clé n’est conservée que sur le serveur et ne doit jamais apparaître dans le code côté client ; en cas de soupçon de fuite, on la renouvelle dans l’espace client, en mettant à jour en même temps la vérification de votre côté.
La nouvelle livraison d’un webhook est normale, pas une panne
L’expéditeur ne peut pas être entièrement certain qu’un code 2xx signifie « événement enregistré » et non « le serveur a répondu, mais le traitement a échoué une seconde plus tard ». C’est pourquoi la plupart des systèmes relancent la livraison du webhook selon un calendrier : après quelques secondes, puis après une minute, et ainsi de suite plusieurs fois, jusqu’à obtenir un accusé de réception ou épuiser la limite de tentatives. Résultat : un même code, avec le même identifiant d’événement, peut arriver deux, voire trois fois.
Le gestionnaire doit être idempotent : avant d’écrire, il vérifie qu’un code portant cet identifiant d’activation ou d’événement n’est pas déjà enregistré, et, en cas de doublon, répond simplement 200 sans rien recréer. Les relances côté expéditeur ressemblent à la façon dont il convient de relancer vos propres requêtes vers l’API d’un tiers ; les principes généraux sont exposés dans l’article erreurs d’API : comment les traiter et relancer. Si le récepteur est resté indisponible pendant toute la fenêtre de relances, l’événement ne sera pas perdu à une seule condition : l’expéditeur dispose d’une file des événements non livrés, et ce qui a été manqué peut être récupéré manuellement par une requête de statut distincte.
Quand le polling reste pertinent
Si la tâche n’a pas d’adresse publique permanente (banc de test sans domaine, script ponctuel sur une machine derrière un NAT, court pilote arrêté au bout d’une journée), mettre en place un webhook n’a pas de sens. Un polling à intervalle de quelques secondes suffit pour une tâche ponctuelle ou rare, sans infrastructure de réception ni signature.
Le second cas est celui de la requête vraiment isolée : un code pour une activation, sans flux d’événements, où le gain du webhook ne justifie pas la configuration d’une adresse publique et d’une file de traitement. Avec une réception de codes régulière ou parallèle, le rapport s’inverse : le polling se met à consommer la limite de l’API plus vite qu’il ne fait gagner du temps d’intégration.
Questions fréquentes
Peut-on utiliser la même adresse de webhook pour plusieurs services ?
Techniquement oui, si le gestionnaire distingue les événements grâce au champ contenant l’identifiant du service ou de l’activation dans le corps de la requête. Il est plus pratique de séparer les sources par des chemins distincts sur un même domaine : les journaux sont plus faciles à lire et l’on peut mettre à jour la signature d’une source sans toucher aux autres.
Que faire si le fournisseur ne prend pas en charge la relance de livraison ?
Mettez en place en parallèle un polling de statut comme filet de sécurité, au cas où le récepteur aurait été indisponible lors de l’unique tentative de push. Interrogez rarement, une fois toutes les quelques minutes : cela suffit pour récupérer l’événement manqué, sans transformer l’interrogation en canal principal.
Comment vérifier que la signature fonctionne correctement avant la mise en production ?
Envoyez un événement de test avec un corps volontairement altéré ou un en-tête de signature erroné et assurez-vous que le gestionnaire le rejette avant toute écriture en base. Recommencez ensuite avec une signature correcte et le même identifiant d’événement, deux fois de suite : le second appel doit renvoyer 200 sans rien créer en double.
Le format de l’événement, l’en-tête de signature, la structure du corps de la requête et les paramètres des nouvelles tentatives pour la réception de codes par webhook sont décrits dans la documentation de l’API.