Écouteur de Webhooks Microsoft Graph | Easy Understand Hermes Agent

Pensez-y de cette façon : au lieu que votre téléphone vérifie constamment votre réfrigérateur pour voir si le lait est épuisé, le réfrigérateur vous envoie un texto dès que le lait est terminé. C’est exactement ce que fait un écouteur webhook — il attend un signal, puis réagit automatiquement.

Qu’est-ce que cela fait concrètement ?

L’écouteur webhook Microsoft Graph est une fonctionnalité de Hermes Agent qui permet à Microsoft 365 (M365) de dire à Hermes quand quelque chose se produit — comme la fin d’une réunion Teams, l’arrivée d’un nouveau message de chat, ou la mise à jour d’un événement de calendrier.

Ce n’est pas un chatbot avec lequel vous discutez. C’est plutôt un assistant silencieux qui écoute les « notifications de changement » provenant de Microsoft Graph, puis déclenche un pipeline pour faire quelque chose d’utile — comme récupérer la transcription d’une réunion et publier un résumé dans Teams.

Ce qu’il vous faut avant de commencer

Vous aurez besoin de trois choses :

Des identifiants d’application Microsoft Graph — enregistrez une application dans le portail Azure de Microsoft.
Une URL HTTPS publique — Microsoft Graph n’appellera pas localhost. Un tunnel de développement fonctionne pour les tests ; un vrai domaine est préférable pour la production.
Un secret robuste — c’est votre valeur clientState, utilisée pour vérifier que les notifications proviennent bien de Microsoft.

Générez un secret avec :

openssl rand -hex 32

Placez-le dans ~/.hermes/.env comme ceci :

MSGRAPH_WEBHOOK_CLIENT_STATE=votre-secret-généré-ici

Configuration de démarrage rapide

Le moyen le plus simple d’activer l’écouteur est d’utiliser un fichier de configuration minimal (~/.hermes/config.yaml) :

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "remplacez-par-un-secret-robuste"
      accepted_resources:
        - "communications/onlineMeetings"

Ou utilisez des variables d’environnement dans ~/.hermes/.env (elles sont automatiquement fusionnées au démarrage) :

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=votre-secret-généré-ici
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Remarque : L’adresse de liaison n’est lue que depuis extra.host dans le fichier de configuration — il n’existe pas de variable d’environnement MSGRAPH_WEBHOOK_HOST pour la remplacer.

Démarrage de l’écouteur

Exécutez cette commande pour démarrer la passerelle :

hermes gateway run

Une fois en cours d’exécution, l’écouteur expose ces points de terminaison :

POST /msgraph/webhook — reçoit les notifications de changement de Microsoft Graph
GET /msgraph/webhook?validationToken=... — gère la poignée de main de validation d’abonnement
GET /health — une sonde de disponibilité avec des compteurs pour les notifications acceptées/dupliquées

Rendre l’écouteur public

Pour que Microsoft Graph puisse atteindre votre écouteur, vous devez l’exposer publiquement. Utilisez un proxy inverse, un tunnel de développement ou une passerelle d’entrée. Votre URL de notification pour les abonnements Graph sera :

https://ops.example.com/msgraph/webhook

Aide-mémoire de configuration

Tous les paramètres se trouvent sous platforms.msgraph_webhook.extra :

Paramètre	Défaut	Rôle
`host`	non défini (toutes les interfaces)	Adresse de liaison. Utilisez `127.0.0.1` pour les tunnels de développement.
`port`	`8646`	Port d’écoute.
`webhook_path`	`/msgraph/webhook`	Chemin où Graph envoie ses POST.
`health_path`	`/health`	Point de terminaison de disponibilité.
`client_state`	—	Votre secret partagé, comparé de manière sécurisée.
`accepted_resources`	`[]` (tout accepter)	Liste blanche des chemins de ressources Graph. Utilisez `*` pour les jokers.

Résumé et conseil pratique

L’écouteur webhook Microsoft Graph est votre pont entre les événements M365 et les actions Hermes. Ce n’est pas compliqué — juste un écouteur qui attend un signal, puis déclenche un flux de travail.

Conseil pratique : Commencez avec accepted_resources limité à une seule ressource (comme communications/onlineMeetings) pour rester simple. Une fois que vous voyez les notifications circuler, élargissez la liste. Et utilisez toujours un client_state correctement généré — c’est votre poignée de main de sécurité avec Microsoft.