如何在向Microsoft Graph的响应中发送202-Accepted状态码？

一、202 Accepted状态码核心含义 #

• 属于HTTP成功类状态码，代表服务端已经成功接收到客户端请求，但尚未完成处理
• 对应Microsoft Graph webhook场景，返回202的作用是告知Graph服务：推送的变更通知已经收到，不需要触发重复推送机制；后续的业务处理逻辑会异步完成，不需要等待处理结束再响应
• 注意不要直接返回200 OK，200代表请求已经处理完成，如果接收通知后需要执行耗时操作（比如数据同步、库表写入、第三方接口调用等），超时未返回的话Graph服务会判定推送失败，触发重复推送，容易导致重复消费问题

二、具体实现方式 #

核心逻辑是webhook接口完成请求校验之后，先返回202状态码，再异步执行后续业务处理逻辑，不同常用后端框架的实现示例如下：

Node.js（Express框架） #

app.post('/graph/webhook', async (req, res) => {
  // 第一步：完成Microsoft Graph请求校验（验证token、签名等，根据订阅配置调整）
  const isValid = validateGraphRequest(req);
  if (!isValid) {
    return res.status(403).send('Invalid request');
  }

  // 第二步：直接返回202状态码，不需要等待业务处理完成
  res.status(202).send();

  // 第三步：异步处理后续业务逻辑，比如解析通知内容、更新数据等
  await processGraphNotification(req.body);
});

Python（FastAPI框架） #

from fastapi import FastAPI, Response, status
import asyncio

app = FastAPI()

@app.post("/graph/webhook")
async def graph_webhook(response: Response, notification: dict):
    # 第一步：校验请求合法性
    is_valid = validate_graph_request(notification)
    if not is_valid:
        response.status_code = status.HTTP_403_FORBIDDEN
        return {"msg": "Invalid request"}
    
    # 第二步：先返回202
    response.status_code = status.HTTP_202_ACCEPTED
    # 第三步：异步执行业务逻辑
    asyncio.create_task(process_notification(notification))
    return {}

Java（Spring Boot框架） #

@RestController
@RequestMapping("/graph")
public class GraphWebhookController {

    @PostMapping("/webhook")
    public ResponseEntity<Void> handleWebhook(@RequestBody String notificationBody, HttpServletRequest request) {
        // 第一步：校验请求合法性
        boolean isValid = validateGraphRequest(request, notificationBody);
        if (!isValid) {
            return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
        }

        // 第二步：异步处理业务逻辑
        new Thread(() -> processNotification(notificationBody)).start();
        // 直接返回202状态码
        return ResponseEntity.accepted().build();
    }
}

三、注意事项 #

• 必须完成请求合法性校验之后再返回202，不要给所有请求直接返回202，避免恶意请求攻击
• 业务处理逻辑一定要异步执行，不能阻塞202的返回流程，否则容易触发Graph的超时重试
• 如果业务逻辑处理失败需要重新接收通知，可以在对应重试周期内返回非202状态码，或者自己实现死信队列处理失败的通知

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