词元之母TOK.MOM - 平台充值汇率 1:1 即 1 人民币充值到账 1 美元，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"Microsoft Graph Webhook 监听器"
Microsoft Graph Webhook 监听器
msgraph_webhook gateway 平台是一个入站事件监听器。它是 Hermes 接收来自 Microsoft Graph 的变更通知的方式——"一个 Teams 会议已结束"、"此聊天中收到了一条新消息"、"此日历事件已更新"。与 teams 平台（用户向其发送消息的聊天机器人）不同——此平台是 M365 告知 Hermes 某事已发生，而非来自用户的消息。/chats/.../messages、/users/.../events）使用同一监听器——流水线消费者通过各自的 PR 接入。前提条件
clientState 的值。使用 openssl rand -hex 32 生成，并以 MSGRAPH_WEBHOOK_CLIENT_STATE 写入 ~/.hermes/.env。快速开始
~/.hermes/config.yaml：~/.hermes/.env 中的环境变量（启动时自动合并）：hermes gateway run。监听器暴露以下端点：POST /msgraph/webhook — 来自 Graph 的变更通知GET /msgraph/webhook?validationToken=... — Graph 订阅验证握手GET /health — 就绪探针，包含已接受/重复计数器/msgraph/webhook：https://ops.example.com/msgraph/webhook配置
platforms.msgraph_webhook.extra 下：| 设置 | 默认值 | 说明 |
|---|---|---|
host | 0.0.0.0 | HTTP 监听器的绑定地址。 |
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 | []（允许全部） | 可选的源 IP 白名单。见下文。 |
MSGRAPH_WEBHOOK_*），在 gateway 启动时合并到配置中——参见环境变量参考。安全加固
clientState 是主要的认证检查
clientState 字符串。监听器使用时序安全比较拒绝任何 clientState 不匹配的通知。这是 Microsoft 的官方机制——请将该值视为强共享密钥。client_state，监听器将接受所有格式正确的 POST 请求。生产环境中请勿在未设置的情况下运行。源 IP 白名单（生产部署）
HTTPS 终止
响应规范
202 Accepted 且响应体为空——内部计数器不会出现在响应中。运维人员可通过 /health 观察计数。| 结果 | 状态码 |
|---|---|
| 通知已接受或已去重 | 202 |
验证握手（带 validationToken 的 GET） | 200（原样回传 token） |
| 批次中所有条目的 clientState 均失败 | 403 |
JSON 格式错误 / 缺少 value 数组 / 未知资源 | 400 |
| 源 IP 不在白名单中 | 403 |
不带 validationToken 的裸 GET | 400 |
故障排查
| 问题 | 检查项 |
|---|---|
| Graph 订阅验证失败 | 公开 URL 可访问，/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 一同发布）。 |
监听器已启动，但 curl http://localhost:8646/health 挂起 | 端口绑定冲突。检查 ss -tlnp | grep 8646，如有需要更改 port:。 |
| 来自 Microsoft 的真实 Graph 请求返回 403 | 源 IP 白名单范围过窄。临时移除 allowed_source_cidrs，确认流量正常后，将列表扩展至包含当前 Microsoft 出口范围。 |
相关文档
修改于 2026-05-31 00:25:01