Guide
Webhook et IA : déclencher un traitement sans rien perdre
Recevoir un webhook, vérifier sa signature, répondre vite, mettre l'appel au modèle en file d'attente : le montage, d'après GitHub et Microsoft Graph.
Mis à jour le
- Le point de réception : une adresse HTTPS publique. Il vérifie l'authenticité, enregistre l'événement et répond aussitôt.
- La file d'attente : elle garde les événements tant qu'ils ne sont pas traités, et absorbe les pics.
- Le travailleur : il prend un événement, relit si besoin la source, appelle le modèle.
- Le modèle : il reçoit seulement les données nécessaires.
- L'action et le journal : écrire le résultat, ou le proposer à un humain, et garder la trace.
Un webhook est un appel HTTP qu'un logiciel envoie à une adresse que vous lui avez donnée, au moment où un événement se produit : un mail arrive, une affaire change d'étape, un ticket est créé. C'est la bonne façon de déclencher une IA, plutôt que d'interroger le logiciel en boucle. Mais la réception doit suivre une règle simple : vérifier, accuser réception très vite, traiter plus tard. Un modèle d'IA est lent à l'échelle d'un webhook ; si vous le faites attendre, l'émetteur considère l'envoi comme raté.
La documentation des événements API d’ALMA donne un contrat concret à examiner pour votre récepteur. Vérifiez la signature, les tentatives et les identifiants effectivement disponibles avant de définir votre traitement des doublons.
Le montage en cinq pièces
Émetteur ──► Point de réception ──► File d'attente ──► Travailleur ──► Modèle d'IA
(CRM, (vérifie, répond (garde les (lit la source, │
Graph…) en < 3 s) événements) appelle l'IA) ▼
Action / journal
- Le point de réception : une adresse HTTPS publique. Il vérifie l'authenticité, enregistre l'événement et répond aussitôt.
- La file d'attente : elle garde les événements tant qu'ils ne sont pas traités, et absorbe les pics.
- Le travailleur : il prend un événement, relit si besoin la source, appelle le modèle.
- Le modèle : il reçoit seulement les données nécessaires.
- L'action et le journal : écrire le résultat, ou le proposer à un humain, et garder la trace.
Les délais imposés par les émetteurs
| Émetteur | Délai pour répondre | Si vous dépassez |
|---|---|---|
| Microsoft Graph | 3 secondes | Nouvelles tentatives pendant 4 heures au plus, avec un délai porté à 10 secondes ; au-delà de seuils de lenteur, notifications retardées puis abandonnées |
| GitHub | 10 secondes, réponse 2XX | L'envoi compte comme un échec |
Microsoft Graph précise ses seuils. Un point de réception est marqué « lent » quand plus de 10 % des réponses dépassent 3 secondes sur dix minutes : les notifications suivantes partent alors avec dix minutes de retard. Il est marqué « drop » au-delà de 15 % de réponses de plus de 10 secondes : les notifications sont abandonnées pendant dix minutes, et une notification abandonnée ne se récupère pas.
D'où la consigne de Microsoft : si vous ne pouvez pas traiter en 3 secondes, validez la notification, mettez-la en file et répondez 202 Accepted. Si vous n'avez pu ni traiter ni mettre en file, répondez par un code 5xx pour que Graph réessaie.
Vérifier l'authenticité
N'importe qui peut envoyer une requête à une adresse publique. Avant de donner un événement à une IA, vérifiez qu'il vient bien de l'émetteur.
Par signature (exemple GitHub). L'émetteur calcule un HMAC (code d'authentification par hachage avec une clé secrète) en SHA-256 du contenu reçu, avec votre secret, et le place dans l'en-tête X-Hub-Signature-256, préfixé par sha256=. Vous refaites le calcul et comparez. GitHub insiste : comparez avec une fonction à temps constant, comme crypto.timingSafeEqual, jamais avec un simple ==. Le secret doit être une chaîne aléatoire longue, gardée côté serveur.
Par valeur partagée (exemple Microsoft Graph). Vous fixez une valeur secrète clientState en créant l'abonnement ; chaque notification la renvoie. Si elle ne correspond pas, la notification n'est pas valide. Graph valide aussi votre adresse à la création de l'abonnement : il envoie un validationToken, que vous devez renvoyer en texte brut, avec un statut 200 OK, dans les 10 secondes. Microsoft conseille d'échapper ce jeton, et permet de n'accepter au pare-feu que les adresses IP de Microsoft Graph.
Ne pas traiter deux fois le même événement
Un émetteur qui réessaie peut livrer le même événement plusieurs fois. Pour une IA qui écrit (répondre à un mail, créer une tâche), un doublon se voit tout de suite. GitHub fournit un identifiant de livraison, l'en-tête X-GitHub-Delivery, qui permet de vérifier que chaque livraison est unique ; une relivraison reprend le même identifiant. Gardez les identifiants déjà traités et ignorez les doublons.
Ne demander que les événements utiles
GitHub recommande de ne s'abonner qu'aux événements nécessaires et de vérifier le type et l'action de chaque événement avant traitement. Pour une IA, c'est aussi une question de coût : chaque événement traité peut déclencher un appel au modèle.
Les autres formes de notification
Tous les émetteurs ne poussent pas un webhook classique :
- HubSpot pousse les données par des actions webhook dans les workflows ; ces appels ne comptent pas dans la limite d'API, mais demandent l'abonnement Marketing Enterprise.
- Gmail passe par Cloud Pub/Sub, avec un
watchà renouveler au moins tous les sept jours et un plafond d'un événement par seconde et par utilisateur (voir Gmail API). - Microsoft Graph peut aussi livrer vers Azure Event Hubs ou Event Grid, que Microsoft suggère si votre point de réception ne tient pas les délais.
Après une panne
Votre point de réception a été arrêté ? Graph réessaie pendant 4 heures au plus. GitHub recommande de relivrer les webhooks manqués une fois le serveur revenu. Dans les deux cas, prévoyez une relecture de la source pour combler les trous : l'IA ne doit pas répondre à un client sur la base d'un état incomplet.
Pour la suite d'un événement côté agent (choisir l'outil, demander une validation), voir Cercle IA Tech · Agents.
Questions fréquentes
Peut-on appeler le modèle d'IA directement dans la réponse au webhook ?
C'est risqué : un modèle peut mettre plusieurs secondes à répondre, alors que Microsoft Graph attend une réponse en moins de 3 secondes et GitHub en moins de 10. Accusez réception, mettez l'événement en file, traitez ensuite.
Comment vérifier qu'un webhook vient bien de l'émetteur ?
Selon l'émetteur : GitHub signe chaque envoi par un HMAC SHA-256 de son contenu avec votre secret, dans l'en-tête X-Hub-Signature-256 ; Microsoft Graph renvoie la valeur secrète clientState que vous avez fixée à l'abonnement.
Sources
Pages consultées pour écrire cet article :
- https://alma.iarche.fr/fr/api-docs
- https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks
- https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
- https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks
- https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines
- https://developers.google.com/workspace/gmail/api/guides/push