Listener Webhook di Microsoft Graph

Pensala così: invece di controllare continuamente il frigo per vedere se il latte è finito, il frigo ti manda un messaggio nel momento esatto in cui finisce. È esattamente ciò che fa un webhook listener — aspetta un segnale, poi reagisce automaticamente.

---

Cosa Fa Esattamente?

Il Microsoft Graph Webhook Listener è una funzionalità di Hermes Agent che permette a Microsoft 365 (M365) di avvisare Hermes quando succede qualcosa — come la fine di una riunione Teams, l’arrivo di un nuovo messaggio in chat o l’aggiornamento di un evento del calendario.

Non è un chatbot con cui parlare. È più simile a un assistente silenzioso che ascolta le “notifiche di modifica” da Microsoft Graph e poi attiva una pipeline per fare qualcosa di utile — come recuperare la trascrizione di una riunione e pubblicare un riepilogo su Teams.

---

Cosa Ti Serve Prima di Iniziare

Ti serviranno tre cose:

1. Credenziali dell’app Microsoft Graph — registra un’app nel portale Azure di Microsoft.
2. Un URL HTTPS pubblico — Microsoft Graph non chiamerà localhost. Un dev tunnel funziona per i test; un dominio reale è il massimo per la produzione.
3. Un segreto robusto — questo è il tuo valore clientState, usato per verificare che le notifiche provengano davvero da Microsoft.

Genera un segreto con:

openssl rand -hex 32

Mettilo in ~/.hermes/.env così:

MSGRAPH_WEBHOOK_CLIENT_STATE=il-tuo-segreto-generato-qui

---

Configurazione Rapida

Il modo più semplice per attivare il listener è con un file di configurazione minimale (~/.hermes/config.yaml):

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "sostituisci-con-un-segreto-robusto"
      accepted_resources:
        - "communications/onlineMeetings"

Oppure usa le variabili d’ambiente in ~/.hermes/.env (vengono unite automaticamente all’avvio):

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=il-tuo-segreto-generato-qui
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

Nota: L’host di bind viene letto solo da extra.host nel file di configurazione — non esiste un override con la variabile d’ambiente MSGRAPH_WEBHOOK_HOST.

---

Avvio del Listener

Esegui questo comando per avviare il gateway:

hermes gateway run

Una volta in esecuzione, il listener espone questi endpoint:

• POST /msgraph/webhook — riceve le notifiche di modifica da Microsoft Graph
• GET /msgraph/webhook?validationToken=... — gestisce la handshake di validazione della sottoscrizione
• GET /health — un probe di prontezza con contatori per notifiche accettate/duplicate

---

Rendere Pubblico il Listener

Perché Microsoft Graph possa raggiungere il tuo listener, devi esporlo pubblicamente. Usa un reverse proxy, un dev tunnel o un ingress. Il tuo URL di notifica per le sottoscrizioni Graph sarà:

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

---

Riepilogo della Configurazione

Tutte le impostazioni si trovano sotto platforms.msgraph_webhook.extra:

Impostazione	Predefinito	Cosa Fa
host	non impostato (tutte le interfacce)	Indirizzo di bind. Usa 127.0.0.1 per i dev tunnel.
port	8646	Porta su cui ascoltare.
webhook_path	/msgraph/webhook	Percorso su cui Graph invia le POST.
health_path	/health	Endpoint di prontezza.
client_state	—	Il tuo segreto condiviso, confrontato in modo sicuro.
accepted_resources	[] (accetta tutto)	Lista consentita dei percorsi delle risorse Graph. Usa * per i caratteri jolly.

---

Riepilogo e Consiglio Pratico

Il Microsoft Graph Webhook Listener è il tuo ponte tra gli eventi M365 e le azioni di Hermes. Non è complicato — è solo un listener che aspetta un segnale e poi attiva un flusso di lavoro.

Consiglio pratico: Inizia con accepted_resources limitato a una sola risorsa (come communications/onlineMeetings) per mantenere le cose semplici. Una volta che vedi arrivare le notifiche, espandi la lista. E usa sempre un client_state generato correttamente — è la tua stretta di mano di sicurezza con Microsoft.

---