API & Webhooks

Poser les bases

API et webhook : deux manières de faire circuler l’information

La seule question qui sépare une API d’un webhook est celle-ci : qui prend l’initiative de l’échange. Avec une API, votre système demande et attend une réponse. Avec un webhook, il ne demande rien : il écoute, et l’application source vient déposer l’information au moment où elle existe. Tout le reste découle de cette inversion.

Cette page traite de la plomberie du déclenchement, pas des API de modèles. Si vous cherchez à appeler un modèle de langage depuis votre code, la page API IA couvre ce sujet. Si vous voulez exposer vos propres outils à un assistant conversationnel, c’est la page MCP et API qui s’en occupe.

Appel d’API et polling : quand interroger un service à intervalle régulier

L’interrogation périodique consiste à demander « quoi de neuf ? » à intervalle fixe. C’est la méthode par défaut quand le service distant n’émet pas de notification, et elle reste parfaitement acceptable dans ce cas. Son coût est simple à comprendre : vous payez des appels qui ne rapportent rien la plupart du temps, et vous acceptez un décalage entre le moment de l’événement et celui où vous l’apprenez.

Deux détails déterminent si un polling tient dans la durée. Le curseur d’abord : mémorisez le dernier élément traité, par identifiant ou par horodatage, et ne redemandez que ce qui a bougé depuis. Le comportement en cas d’échec ensuite : si un cycle est manqué, le suivant doit rattraper l’intervalle perdu, sans quoi vous perdez des événements sans le savoir.

Webhook entrant et webhook sortant : qui appelle qui

Un webhook entrant est une adresse que vous exposez et qu’un tiers appelle ; un webhook sortant est un appel que vous émettez vers une adresse fournie par quelqu’un d’autre. Vous n’avez pas les mêmes responsabilités des deux côtés, et c’est la source de la plupart des malentendus en intégration.

Côté entrant, vous répondez de trois choses : la disponibilité de l’adresse, la vérification que l’appel vient bien de qui il prétend, et la rapidité de la réponse. Côté sortant, vos obligations changent : stabilité du format envoyé, gestion des tentatives quand le destinataire ne répond pas, conservation des messages non délivrés. Écrivez qui porte quoi avant de coder, surtout quand les deux extrémités appartiennent à des prestataires différents.

Choisir la méthode

Webhook, cron ou API : quelle méthode de déclenchement choisir

Le choix se ramène à trois questions : le service distant sait-il notifier, quel décalage acceptez-vous entre l’événement et son traitement, et qui porte la complexité de la fiabilité. Une intégration mélange souvent plusieurs méthodes, et c’est un signe de bonne conception.

Méthode	Qui prend l’initiative	Cas où elle s’impose	Point de vigilance
Webhook entrant	L’application source, au moment de l’événement	Traitement immédiat attendu, événements peu fréquents mais urgents	Il faut exposer une adresse publique, la sécuriser et absorber les doublons
Interrogation périodique	Vous, à intervalle planifié	Le service distant n’émet aucune notification	Décalage inévitable et appels inutiles la plupart du temps
Appel d’API à la demande	Vous, au moment où vous avez besoin de la donnée	Lecture ponctuelle, vérification avant écriture, enrichissement	Ne détecte rien : vous ne saurez jamais qu’un événement a eu lieu
File d’attente entre les deux	Le producteur dépose, le consommateur retire	Volumes irréguliers, traitements longs, tolérance aux pannes exigée	Composant supplémentaire à héberger, à superviser et à purger

Sur le terrain

Cas d’usage

• Déclencher une automatisation dès la soumission d’un formulaire sur le site
• Recevoir les événements de paiement d’un prestataire et mettre à jour la commande
• Notifier une équipe dans sa messagerie dès qu’un ticket critique est ouvert
• Synchroniser deux applications métier en événementiel plutôt qu’en export nocturne

Vos questions

Questions fréquentes

Quelle différence exacte entre une API et un webhook ?

L’API se consulte, le webhook se reçoit. Dans le premier cas vous posez une question et obtenez une réponse à l’instant où vous la posez ; dans le second, vous êtes prévenu au moment où l’événement se produit, sans avoir rien demandé.

La nuance opérationnelle est qu’un webhook transporte rarement toute l’information dont vous avez besoin. Il annonce qu’une commande a changé d’état, pas le détail complet de la commande. Prévoyez donc presque toujours un appel d’API en complément, déclenché par le webhook, pour aller lire l’état réel plutôt que de faire confiance au contenu du message.

Comment sécuriser un endpoint qui reçoit des webhooks publics ?

Par la vérification de signature, avant toute autre chose. L’émetteur signe le corps du message avec un secret partagé, vous recalculez la signature à la réception et vous rejetez ce qui ne correspond pas. Ajoutez une vérification d’horodatage pour refuser les messages trop anciens, et servez l’endpoint en HTTPS uniquement.

Le piège concret est de vérifier la signature après avoir désérialisé et reformaté le corps du message : l’empreinte porte sur les octets reçus, pas sur votre représentation interne. Conservez le corps brut pour le calcul. Une restriction par plages d’adresses complète le dispositif sans le remplacer, et se périme quand l’émetteur change d’infrastructure.

Que faire si le service destinataire est indisponible au moment de l’envoi ?

Le message doit être conservé et réémis plus tard, avec des tentatives espacées de plus en plus longuement. Sans cette mise en attente, une indisponibilité passagère du destinataire se traduit par une perte définitive de l’événement.

Le piège est de réessayer indéfiniment. Fixez un nombre maximal de tentatives, puis déplacez le message dans une file d’échec consultable, avec le motif du rejet. Distinguez surtout l’erreur temporaire, qui mérite d’être rejouée, du refus définitif pour message invalide, qui sera refusé à l’identique à chaque tentative.

Comment éviter qu’un même événement soit traité deux fois ?

En stockant l’identifiant unique de chaque événement reçu et en ignorant ceux qui figurent déjà dans cette table. C’est le seul mécanisme fiable, car vous ne pouvez pas empêcher l’émetteur de renvoyer un message qu’il croit non délivré.

Le piège se situe dans le choix de la clé. Une empreinte du contenu ne suffit pas : deux événements légitimes peuvent partager le même corps. Utilisez l’identifiant fourni par l’émetteur quand il existe et, à défaut, une combinaison stable de champs métier. Prévoyez une durée de conservation de cette table, sinon elle grossit sans fin.