Microsoft Graph Webhook订阅验证失败问题求助

问题描述 #

在实现Microsoft Graph Webhook订阅功能时，始终遇到验证失败错误：

GraphError: Subscription validation request failed. Notification endpoint must respond with 200 OK to validation request.

处理验证请求的代码片段（NestJS）：

@Post('event')
async eventWebhook(@Req() req, @Res() res) {
    if (req.query && req.query.validationToken) {
        res.set('Content-Type', 'text/plain');
        res.send(200, req.query.validationToken);
        return;
    }
    //... 其他事件处理逻辑
}

使用Postman模拟验证请求时响应正常：

• 请求：

curl --location --request POST 'api.com/event?validationToken=somethin'

• 响应：

200 OK | 641 ms | 312 B
body : somethin

已确认以下内容：

• 端点URL与订阅设置完全一致
• 服务器可公开访问，无网络/防火墙问题
• 中间件和路由未干扰验证请求
• 响应无意外头部
• 服务器POST请求配置正确

完整错误栈：

GraphError: Subscription validation request failed. Notification endpoint must respond with 200 OK to validation request.
    at new GraphError (/usr/src/app/node_modules/@microsoft/microsoft-graph-client/lib/src/GraphError.js:34:28)
    at Function.GraphErrorHandler.constructErrorFromResponse (/usr/src/app/node_modules/@microsoft/microsoft-graph-client/lib/src/GraphErrorHandler.js:63:22)
    at Function.<anonymous> (/usr/src/app/node_modules/@microsoft/microsoft-graph-client/lib/src/GraphErrorHandler.js:91:48)
    at step (/usr/src/app/node_modules/tslib/tslib.js:193:27)
    at Object.next (/usr/src/app/node_modules/tslib/tslib.js:174:57)
    at /usr/src/app/node_modules/tslib/tslib.js:167:75
    at new Promise (<anonymous>)
    at Object.__awaiter (/usr/src/app/node_modules/tslib/tslib.js:163:16)
    at Function.GraphErrorHandler.getError (/usr/src/app/node_modules/@microsoft/microsoft-graph-client/lib/src/GraphErrorHandler.js:87:24)
    at GraphRequest.<anonymous> (/usr/src/app/node_modules/@microsoft/microsoft-graph-client/lib/src/GraphRequest.js:315:84) {
  statusCode: 400,
  code: 'InvalidRequest',
  requestId: 'uuid',
  date: Date obj,
  body: '{"code":"InvalidRequest","message":"Subscription validation request failed. Notification endpoint must respond with 200 OK to validation request.","innerError":{"date":"Date obj","request-id":"uuid","client-request-id":"uuid
  headers: Headers {
    [Symbol(map)]: [Object: null prototype] {
      'cache-control': [Array],
      'transfer-encoding': [Array],
      'content-type': [Array],
      'content-encoding': [Array],
      vary: [Array],
      'strict-transport-security': [Array],
      'request-id': [Array],
      'client-request-id': [Array],
      'x-ms-ags-diagnostic': [Array],
      date: [Array],
      connection: [Array]
    }
  }

排查方向与解决方案 #

1. 修正响应代码的严格性 #

Microsoft Graph对验证响应的要求极为严格，需确保：

• 明确设置状态码为200，而非依赖res.send的参数传递
• 响应体完全等于validationToken，无任何额外字符（空格、换行等）
• Content-Type严格为text/plain

修改后的代码：

@Post('event')
async eventWebhook(@Req() req, @Res() res) {
    if (req.query?.validationToken) {
        // 明确设置状态码，清除可能的空白字符，严格设置Content-Type
        res.status(200)
           .set('Content-Type', 'text/plain')
           .send(req.query.validationToken.trim());
        return;
    }
    //... 其他事件处理逻辑
}

2. 检查服务器端请求日志 #

在服务器上记录Graph发送的验证请求完整信息，包括：

• 请求方法（确认是否为POST）
• Query参数中的validationToken是否完整传递
• 请求头信息
• 服务器处理请求的耗时

反向代理（如Nginx）可能会修改或截断请求参数，需确认代理配置是否保留了完整的query字符串。

3. 确认响应超时 #

Graph对验证请求的响应超时通常在10秒以内，若服务器处理请求延迟超过该时间，会判定验证失败。检查服务器的响应时间，确保在10秒内返回结果。

4. 验证HTTPS证书有效性 #

Graph要求端点必须使用受信任的公共CA颁发的HTTPS证书，自签名证书或过期/域名不匹配的证书会导致请求失败。确认服务器证书状态正常。

5. 检查CORS配置 #

虽然Graph的验证请求通常不会触发CORS预检，但如果服务器的CORS设置过于严格，可能会影响请求处理。确保CORS配置允许所有来源（或Graph的特定域名）访问端点。

内容的提问来源于stack exchange，提问作者ponez