OpenAI 后台响应怎么用 webhook 接收完成事件

我第一次把长时间运行的 Responses API 请求从轮询改成 webhook 时，最容易混淆的是两个对象：后台响应负责承载任务，webhook 事件负责告诉服务端“这个响应已经进入完成状态”。事件体里的 data.id 是关联键，不是完整答案本身。接入时应先校验原始请求体的签名，再用这个 ID 取回完整响应。

官方地址：https://developers.openai.com/api/docs/guides/webhooks

最小可靠链路是：创建带 background: true 的响应，在平台订阅 response.completed，服务端保留原始 body 完成 webhooks.unwrap，最后用 event.data.id 调用 responses.retrieve。

先把后台响应和完成事件分开

后台模式把响应生成放到异步任务中，创建接口很快返回一个响应对象；这个对象的状态还可能是 queued 或 in_progress。webhook 并不是另一种响应存储，而是状态变化的通知入口。本文只处理完成事件，不把取消、失败和业务队列选型混进同一段代码。

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.2",
  input: "整理一份接口变更摘要",
  // 让长任务在后台运行，后续由 webhook 通知完成状态
  background: true,
});

console.log(response.id, response.status); // 先保存响应 ID，状态可能尚未完成

这里的关键迁移点是保存响应 ID。后续 webhook 只需要用同一个 ID 找回完整对象，因此不要把“创建接口返回的当前状态”当成最终输出。

平台配置与签名密钥要一起迁移

在 OpenAI 平台的 webhook 设置中创建端点，并订阅 response.completed。平台会提供签名密钥，服务端通过环境变量读取它。密钥不应写进仓库、请求日志或文章示例中的真实配置。

# 只在服务进程环境中注入签名密钥，不要把真实值提交到仓库
export OPENAI_WEBHOOK_SECRET="your-webhook-signing-secret"

# 端点需要是外部服务可以访问的 HTTPS 地址，例如 /openai/webhook
export OPENAI_WEBHOOK_PATH="/openai/webhook"

如果从轮询迁移过来，回归检查应确认平台事件类型、端点路径和环境变量名称三者一致。只改服务端路由而忘记平台订阅，通常不会得到任何完成通知。

原始 body 不要先被 JSON 中间件改写

签名校验依赖收到的原始请求体。Express 里如果先使用 express.json()，请求可能已经被解析和重序列化，SDK 就无法按原始字节完成校验。下面用文本中间件保留原文，再交给官方 SDK 的 webhooks.unwrap。

import express from "express";
import OpenAI, { InvalidWebhookSignatureError } from "openai";

const app = express();
const client = new OpenAI({
  webhookSecret: process.env.OPENAI_WEBHOOK_SECRET,
});

// 先保留原始文本，签名校验完成后再让 SDK 解包 JSON
app.use(express.text({ type: "application/json" }));

app.post("/openai/webhook", async (req, res) => {
  try {
    // unwrap 同时读取原始 body 和请求头，签名或时间戳不对会抛错
    const event = await client.webhooks.unwrap(req.body, req.headers);
    console.log("verified event:", event.type);
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof InvalidWebhookSignatureError) {
      // 无法证明来源时拒绝请求，不把未校验数据交给业务逻辑
      return res.status(400).send("Invalid signature");
    }
    // 其它异常交给框架错误处理器，避免伪装成成功响应
    return res.sendStatus(500);
  }
});

app.listen(8000, () => {
  console.log("webhook endpoint listening on 8000");
});

这一步的顺序比具体框架更重要：先保留原始 body，再校验签名，最后才读取事件字段。迁移时不要为了复用全局 JSON 中间件而牺牲这一边界。

response.completed 只拿 ID，完整内容要主动取回

完成事件的核心字段是 event.data.id。收到事件并通过签名校验后，再调用 client.responses.retrieve 获取完整响应；这样可以把“通知”和“数据读取”拆开，代码也更容易对失败重试做幂等处理。

app.post("/openai/webhook", async (req, res) => {
  try {
    // 必须在业务分派前完成签名校验
    const event = await client.webhooks.unwrap(req.body, req.headers);

    if (event.type === "response.completed") {
      const responseId = event.data.id;
      // 事件只提供关联 ID，完整输出需要再次读取 Responses API
      const completed = await client.responses.retrieve(responseId);
      console.log("completed response:", responseId);
      console.log(completed.output_text);
    }

    // 已接收并校验的事件及时返回 200，避免发送方重复投递
    return res.sendStatus(200);
  } catch (error) {
    if (error instanceof InvalidWebhookSignatureError) {
      return res.status(400).send("Invalid signature");
    }
    // 读取响应失败时保留非 2xx，让上游按其重试策略处理
    return res.sendStatus(500);
  }
});

如果只打印事件 JSON 而不再取回响应，看到的通常只是事件类型和 ID；如果把 retrieve 写在签名校验之前，则会把未经确认来源的数据带入业务层，这两种写法都不适合作为迁移后的正式入口。

迁移完成后的回归检查清单

生产环境还应按响应 ID 做幂等记录，因为通知入口的职责是接收事件，不能假设每个事件只到达一次。对未知事件先记录类型并返回合适状态，不要把所有事件都强行当成完成事件解析。

相关问题

为什么 webhook 收到了却拿不到文本？先确认是否使用了 response.completed，再检查是否用 event.data.id 调用了 retrieve；事件本身不是完整输出对象。

为什么签名校验总是失败？优先检查原始 body 是否被 JSON 中间件改写，以及 OPENAI_WEBHOOK_SECRET 是否对应当前平台端点。