Microsoft Graph-Webhook-Listener | Easy Understand Hermes Agent

Stell es dir so vor: Statt dass dein Handy ständig den Kühlschrank checkt, ob die Milch alle ist, schickt dir der Kühlschrank eine Nachricht, sobald die Milch leer ist. Genau das macht ein Webhook-Listener – er wartet auf ein Signal und reagiert dann automatisch.

Was macht das eigentlich?

Der Microsoft Graph Webhook Listener ist eine Funktion in Hermes Agent, mit der Microsoft 365 (M365) Hermes mitteilen kann, wenn etwas passiert – zum Beispiel wenn ein Teams-Meeting endet, eine neue Chat-Nachricht eintrifft oder ein Kalenderereignis aktualisiert wird.

Das ist kein Chat-Bot, mit dem du redest. Es ist eher wie ein stiller Assistent, der auf „Änderungsbenachrichtigungen“ von Microsoft Graph lauscht und dann eine Pipeline auslöst, um etwas Nützliches zu tun – wie zum Beispiel ein Meeting-Transkript abzurufen und eine Zusammenfassung zurück in Teams zu posten.

Was du vor dem Start brauchst

Du brauchst drei Dinge:

Microsoft-Graph-App-Anmeldeinformationen – Registriere eine App im Azure-Portal von Microsoft.
Eine öffentliche HTTPS-URL – Microsoft Graph ruft kein localhost auf. Ein Dev-Tunnel funktioniert zum Testen; eine echte Domain ist am besten für die Produktion.
Ein starkes Geheimnis – das ist dein clientState-Wert, mit dem überprüft wird, dass Benachrichtigungen wirklich von Microsoft stammen.

Erzeuge ein Geheimnis mit:

openssl rand -hex 32

Lege es in ~/.hermes/.env ab, so:

MSGRAPH_WEBHOOK_CLIENT_STATE=dein-generiertes-geheimnis-hier

Schnellstart-Einrichtung

Der einfachste Weg, den Listener zu aktivieren, ist eine minimale Konfigurationsdatei (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "ersetze-mit-einem-starken-geheimnis"
      accepted_resources:
        - "communications/onlineMeetings"

Oder verwende Umgebungsvariablen in ~/.hermes/.env (diese werden beim Start automatisch zusammengeführt):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=dein-generiertes-geheimnis-hier
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Hinweis: Die Bind-Adresse wird nur aus extra.host in der Konfigurationsdatei gelesen – es gibt keine MSGRAPH_WEBHOOK_HOST-Umgebungsvariable zum Überschreiben.

Listener starten

Führe diesen Befehl aus, um das Gateway zu starten:

hermes gateway run

Sobald es läuft, stellt der Listener diese Endpunkte bereit:

POST /msgraph/webhook – empfängt Änderungsbenachrichtigungen von Microsoft Graph
GET /msgraph/webhook?validationToken=... – behandelt den Validierungs-Handshake für Abonnements
GET /health – ein Bereitschafts-Endpunkt mit Zählern für akzeptierte/doppelte Benachrichtigungen

Öffentlich erreichbar machen

Damit Microsoft Graph deinen Listener erreichen kann, musst du ihn öffentlich zugänglich machen. Verwende einen Reverse-Proxy, Dev-Tunnel oder Ingress. Deine Benachrichtigungs-URL für Graph-Abonnements lautet dann:

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

Konfigurations-Spickzettel

Alle Einstellungen liegen unter platforms.msgraph_webhook.extra:

Einstellung	Standard	Funktion
`host`	nicht gesetzt (alle Schnittstellen)	Bind-Adresse. Verwende `127.0.0.1` für Dev-Tunnel.
`port`	`8646`	Port, auf dem gelauscht wird.
`webhook_path`	`/msgraph/webhook`	Pfad, an den Graph POST-Anfragen sendet.
`health_path`	`/health`	Bereitschafts-Endpunkt.
`client_state`	—	Dein gemeinsames Geheimnis, sicher verglichen.
`accepted_resources`	`[]` (alle akzeptieren)	Whitelist der Graph-Ressourcenpfade. Verwende `*` für Platzhalter.

Zusammenfassung & praktischer Tipp

Der Microsoft Graph Webhook Listener ist deine Brücke zwischen M365-Ereignissen und Hermes-Aktionen. Er ist nicht kompliziert – nur ein Listener, der auf ein Signal wartet und dann einen Workflow auslöst.

Praktischer Tipp: Beginne mit accepted_resources, begrenzt auf eine Ressource (wie communications/onlineMeetings), um es einfach zu halten. Sobald du siehst, dass Benachrichtigungen fließen, erweitere die Liste. Und verwende immer ein ordentlich generiertes client_state – es ist dein Sicherheits-Handshake mit Microsoft.