SuperAPI AI 工具集

microsoft-graph-webhooks

通用与其它

查看项目

更新于 10-15 22:14

技能介绍

用途:接收并校验 Microsoft Graph 变更通知(Webhook),用于搭建订阅(subscription)/通知处理器。

主要能力:处理三类校验。一是端点验证握手:创建订阅或变更 notificationUrl 时,Graph 会向 POST <notificationUrl>?validationToken={token} 发送空请求体,需在 10 秒内将 URL 解码后的 token 以 text/plain、HTTP 200 回显,否则订阅创建失败。二是 clientState:创建订阅时设置的不透明共享密钥(最长 128 字符),Graph 在每条通知的 clientState 字段回显,需与存储值做时间安全比较,不匹配即拒绝。三是仅富通知使用的 validationTokens:当 includeResourceData: true 时,每次 POST 带由 Microsoft 身份平台签名的 JWT 数组,资源数据经 AES 加密。

通知与响应:普通通知是 value 下的批数组,含 subscriptionId、changeType、resource、clientState、tenantId、resourceData 等字段;需在 3 秒内返回 202 Accepted 并异步处理,失败投递会退避重试最长 4 小时。changeType 可选 created、updated、deleted(created 不支持 user/group;driveItem 根与 SharePoint 列表仅支持 updated),可用逗号组合。

生命周期事件:发往独立的 lifecycleNotificationUrl,位于 lifecycleEvent 字段,包括 reauthorizationRequired(需 reauthorize 或 PATCH 新过期时间)、subscriptionRemoved(重建后经 delta 查询重新同步)、missed(经 delta 查询补同步)。订阅寿命较短并需在 expirationDateTime 前通过 PATCH /subscriptions/{id} 续订:presence 约 1 小时,Teams chatMessage/channel/chat 与群组会话约 3 天,Outlook 消息/事件/联系人约 7 天(含资源数据约 1 天),driveItem 与 SharePoint 列表约 30 天,user/group 约 29 天,安全警报约 30 天。

用法与限制:需要环境变量 MICROSOFT_GRAPH_CLIENT_STATE;订阅创建/续订辅助还需要 MICROSOFT_TENANT_ID、MICROSOFT_CLIENT_ID、MICROSOFT_CLIENT_SECRET、NOTIFICATION_URL、GRAPH_USER_ID、GRAPH_RESOURCE、GRAPH_CHANGE_TYPES。本地开发可运行 npx hookdeck-cli listen 3000 microsoft-graph --path /webhooks/microsoft-graph。仅应用认证不能使用 /me。资料未提供定价与更多平台限制。