Microsoft Graph Webhook 监听器

這篇教學講的是：如何讓 Hermes Agent 接收來自微軟 365（Microsoft Graph）的「事件通知」，比如會議結束、新訊息到達、日曆更新——相當於給 Hermes 裝了一個「門鈴」，微軟一有動靜就按鈴告訴它。

---

先打個比方

想像你有一個私人助理（Hermes），它需要知道「會議室裡會議開完了」才能去收拾。但助理不能一直盯著會議室看，所以微軟答應：一有變化就打電話通知助理。這個「電話線路」就是 Webhook 監聽器。而「電話號碼」就是你的公網網址。

---

準備工作（第 1 步）

你需要三樣東西：

1. 一個微軟 Graph 應用程式憑證（相當於「電話號碼本」裡的註冊資訊），註冊方法見官方指南。
2. 一個公網 HTTPS 位址——微軟不會給「內線電話」打電話，所以你得有一個像 https://ops.example.com 這樣的網址。開發時可以用臨時隧道（dev tunnel），生產環境必須用正式網域名稱和憑證。
3. 一個強密碼（叫 clientState），用來確認「電話是微軟打來的，不是騙子」。產生方法：

openssl rand -hex 32

把產生的值存到 ~/.hermes/.env 裡：

MSGRAPH_WEBHOOK_CLIENT_STATE=你產生的密碼

---

快速啟動（第 2 步）

在 ~/.hermes/config.yaml 裡寫最小設定：

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "替換成你的強密碼"
      accepted_resources:
        - "communications/onlineMeetings"

accepted_resources 是「允許哪些類型的事件通知」，這裡只接收「線上會議」相關事件。

然後啟動閘道：

hermes gateway run

監聽器會開三個「介面」：

• POST /msgraph/webhook —— 微軟發通知的入口
• GET /msgraph/webhook?validationToken=... —— 微軟驗證「電話線通不通」的握手
• GET /health —— 健康檢查

最後，把你的公網位址指向這個監聽器，通知位址就是：

https://你的網域名稱/msgraph/webhook

---

設定項目速查（第 3 步）

設定	預設值	說明
host	全部網路卡	監聽位址。非本機位址必須設定 allowed_source_cidrs
port	8646	連接埠
client_state	無	共用密碼，不設定就拒絕啟動
accepted_resources	全部接受	允許的 Graph 資源路徑，如 "chats/*/messages"
allowed_source_cidrs	空	允許的 IP 區段，生產環境建議填微軟官方網段

---

安全強化（第 4 步）

• clientState 是第一道鎖：每次通知都帶這個密碼，對不上就拒收（用防時序攻擊的比較方式）。
• 生產環境限制來源 IP：只允許微軟的 Graph 伺服器存取。在設定裡加：

allowed_source_cidrs:
  - "52.96.0.0/14"
  - "52.104.0.0/14"

注意：微軟的 IP 區段會變，建議每季複查一次。

• HTTPS 由反向代理處理：監聽器本身只講 HTTP，用 Caddy、Nginx 或 Cloudflare Tunnel 在外面套一層 HTTPS 即可。
• 回應乾淨：成功時回傳 202，不洩漏內部計數。狀態碼速查：驗證握手回傳 200，密碼錯回傳 403，格式錯回傳 400。

---

常見問題（第 5 步）

問題	檢查什麼
訂閱驗證失敗	公網位址通不通？路徑對不對？validationToken 是否原樣回傳？
有通知但沒處理	client_state 是否和訂閱時一致？accepted_resources 是否包含該資源？
全部 403	密碼不匹配，重新訂閱
啟動報錯	非本機綁定必須設定 allowed_source_cidrs
/health 卡住	連接埠被占用，用 ss -tlnp | grep 8646 查

---

小結

這個監聽器就是 Hermes 的「耳朵」——專門聽微軟 365 的動靜。設定好公網位址、密碼和允許的資源，它就能穩定接收會議結束、新訊息等事件，觸發後續的總結流程。核心三件事：公網可達、密碼一致、IP 白名單。

下篇預告：既然 Hermes 能「聽」到會議結束，那它怎麼把會議紀錄發回 Teams 聊天裡？下一篇我們講 Teams 訊息傳送平台——讓 Hermes 從「聽眾」變成「發言人」。

---