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 从“听众”变成“发言人”。