The Hermes Bible — 繁體中文版

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/msgraph-webhook

msgraph_webhook 閘道平台是一個接收端事件監聽器。它是 Hermes 從 Microsoft Graph 接收變更通知的方式——「Teams 會議結束了」、「新的訊息出現在這個聊天中」、「這個行事曆事件已被更新」。與 teams 平台（使用者可以輸入訊息的聊天機器人）不同——這個平台是 M365 告訴 Hermes 發生了什麼事，而不是使用者。

目前主要的消費者是 Teams 會議摘要管線：Graph 在會議產生逐字稿時發出通知，管線擷取它，然後 Hermes 將摘要發回 Teams。其他 Graph 資源（/chats/.../messages、/users/.../events）使用相同的監聽器——管線消費者會透過各自的 PR 進駐。

前置需求

Microsoft Graph 應用程式憑證——註冊 Microsoft Graph 應用程式
Microsoft Graph 可以存取的公開 HTTPS 網址（Graph 不會呼叫私人端點）。開發隧道適用於測試；正式環境需要具有有效憑證的正式網域。
用於 clientState 值的強共用密鑰。使用 openssl rand -hex 32 產生，並將其放入 ~/.hermes/.env 中的 MSGRAPH_WEBHOOK_CLIENT_STATE。

快速開始

最小化的 ~/.hermes/config.yaml：

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 127.0.0.1
      port: 8646
      client_state: "replace-with-a-strong-secret"
      accepted_resources:
        - "communications/onlineMeetings"

或透過 ~/.hermes/.env 中的環境變數設定（啟動時自動合併）：

MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<generate-with-openssl-rand-hex-32>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

注意：綁定主機是從 config.yaml 中的 extra.host 讀取的（見上方範例）；沒有 MSGRAPH_WEBHOOK_HOST 環境變數覆寫。

啟動閘道：hermes gateway run。監聽器提供以下端點：

POST /msgraph/webhook——來自 Graph 的變更通知
GET /msgraph/webhook?validationToken=...——Graph 訂閱驗證交握
GET /health——就緒探測，包含已接受/重複計數器

將監聽器公開暴露（反向代理、開發隧道、入口控制器）。你在 Graph 訂閱中的通知網址是你的公開 HTTPS 來源加上 /msgraph/webhook：

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

設定

所有設定位於 platforms.msgraph_webhook.extra 下：

設定	預設值	說明
`host`	`0.0.0.0`	HTTP 監聽器的綁定地址。非迴圈綁定需要設定 `allowed_source_cidrs`；迴圈綁定（`127.0.0.1` / `::1`）是最簡單的開發隧道/反向代理設定方式。
`port`	`8646`	綁定連接埠。
`webhook_path`	`/msgraph/webhook`	Graph POST 請求的 URL 路徑。
`health_path`	`/health`	就緒端點。
`client_state`	—	Graph 在每個通知中回傳的共用密鑰。使用 `hmac.compare_digest` 進行比較——使用 `openssl rand -hex 32` 產生。
`accepted_resources`	`[]`（接受所有）	Graph 資源路徑/模式的允許清單。尾部 `` 作為前置比對。允許前置 `/`。範例：`["communications/onlineMeetings", "chats//messages"]`。
`max_seen_receipts`	`5000`	通知 ID 的去重快取大小。達到上限時會淘汰最舊的項目。
`allowed_source_cidrs`	`[]`	非迴圈綁定時必填。僅在監聽器綁定到迴圈地址並由本地隧道/反向代理提供服務時留空。

大多數設定也有對應的環境變數（MSGRAPH_WEBHOOK_*），會在閘道啟動時合併到設定中（例外是 host，僅限設定檔——見上方說明）——詳見環境變數參考。

安全強化

clientState 是主要的驗證機制

每個 Graph 通知都包含你的訂閱所登錄的 clientState 字串。監聽器會拒絕任何 clientState 不符的通知，並使用時間安全的比較方式。這是 Microsoft 文件記錄的機制——請將此值視為強共用密鑰。

如果 client_state 未設定，監聽器將拒絕啟動。

來源 IP 允許清單（正式環境部署）

在正式環境中，應將監聽器限制為 Microsoft 公布的 Graph webhook 來源 IP 範圍。Microsoft 在 Office 365 IP 位址和 URL 網路服務中記錄了這些出口範圍。設定方式如下：

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      host: 0.0.0.0
      client_state: "..."
      allowed_source_cidrs:
        - "52.96.0.0/14"
        - "52.104.0.0/14"
        # ...加入目前 Microsoft 365 "Common" + "Teams" 類別的出口範圍

或透過環境變數設定：

MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS="52.96.0.0/14,52.104.0.0/14"

如果未設定 allowed_source_cidrs，啟動時會拒絕綁定非迴圈主機（如 0.0.0.0、:: 或區域網路 IP）。如果你在同一台機器上使用開發隧道或反向代理，應將 Hermes 綁定到 127.0.0.1 或 ::1，並保持允許清單為空。無效的 CIDR 字串會記錄警告並被忽略。請每季檢查一次 Microsoft IP 清單——它會變動。

HTTPS 終止

監聽器使用純 HTTP 通訊。請在你的反向代理（Caddy、Nginx、Cloudflare Tunnel、AWS ALB）終止 TLS，並透過區域網路將流量轉發到監聽器。Graph 拒絕將訊息傳送到非 HTTPS 端點，因此 Graph 本身不會有未加密的流量到達你。

回應安全性

成功時監聽器回傳 202 Accepted，回應主體為空——內部計數器不會出現在網路回應中。管理員可透過 /health 觀察計數，該端點與 webhook 路徑使用相同的來源 IP 規則保護。

狀態碼一覽：

結果	狀態碼
通知已接受或已去重	202
驗證交握（GET 並帶有 `validationToken`）	200（回傳 token）
批次中所有項目的 clientState 驗證失敗	403
格式錯誤的 JSON / 缺少 `value` 陣列 / 未知資源	400
來源 IP 不在允許清單中	403
沒有 `validationToken` 的純 GET 請求	400

疑難排解

問題	檢查事項
Graph 訂閱驗證失敗	公開網址可存取、`/msgraph/webhook` 路徑相符、帶有 `validationToken` 的 GET 請求在 10 秒內以 `text/plain` 完整回傳 token。
通知已 POST 但未被接收	`client_state` 與你登錄訂閱時使用的值相符。如果值已變更，請重新執行 `openssl rand -hex 32` 並建立新訂閱。檢查 `accepted_resources` 是否包含 Graph 傳送的資源路徑。
每個通知都回傳 403	`clientState` 不相符（偽造的，或訂閱使用了不同的值）。使用 `hermes teams-pipeline subscribe --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE" ...` 重新建立訂閱（需搭配管線執行時的 PR）。
監聽器拒絕在 `0.0.0.0` 上啟動	將 `allowed_source_cidrs` 設為 Microsoft 目前的 webhook 出口範圍，或將 Hermes 綁定到隧道或反向代理後方的 `127.0.0.1` / `::1`。
監聽器已啟動但 `curl http://localhost:8646/health` 無回應	連接埠綁定衝突。請檢查 `ss -tlnp \| grep 8646`，並在需要時更改 `port:`。
來自 Microsoft 的實際 Graph 請求被回傳 403	來源 IP 允許清單過於嚴格。請擴大清單以包含 Microsoft 目前的出口範圍。如果你仍在驗證隧道路徑，請將 Hermes 綁定到迴圈地址，讓隧道處理公開暴露。