OpenAI webhook 事件失败后怎么区分完成取消和失败状态

接 OpenAI webhook 时，最容易出现的错误不是收不到请求，而是把三种不同的终态都写成“任务成功”。response.completed、response.cancelled 和 response.failed 都能用 data.id 找到对应的后台响应，但它们代表的业务结果完全不同：完成才适合落最终结果，取消应该停止等待，失败则要保留失败状态。

官方文档：https://developers.openai.com/api/docs/guides/webhooks

事件参考：https://developers.openai.com/api/reference/resources/webhooks

三类事件其实共享同一个外壳

官方事件参考给出的公共字段包括事件自身的 id、事件类型 type、创建时间 created_at 和 data.id。其中 data.id 是后台 response 的标识，适合关联本地任务表；它只是关联线索，不表达成功或失败。

我更愿意把 webhook 看成“状态通知”，而不是“结果正文”。接收器先判断事件类型，再决定是否需要用这个响应 ID 读取或更新本地记录。这样做的好处是，字段结构相似时，语义不会被相似的 JSON 外壳带偏。

真正要分开的，是业务状态

三种事件的分支可以先用下面这张表固定下来。不要因为 response.cancelled 和 response.failed 都没有最终答案，就把它们合并成一个模糊的“异常”；取消通常是明确的终止意图，失败则是处理没有成功完成。

这里有一个很实用的判断：completed、cancelled、failed 是互斥的终态分支，不能用“有没有 data.id”来判断成功。三者都可能有这个字段。

先验签，再按 type 分派

官方 SDK 的 webhooks.unwrap() 会在一次调用中校验签名并解析事件。签名校验需要原始请求体，所以 Express 这里不能先用会把 body 解析成对象的中间件。验签成功后，再读取 event.type 才能信任它。

import express from "express";
import OpenAI from "openai";

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

// 保留原始文本，官方 SDK 需要它参与 webhook 签名校验。
app.use(express.text({ type: "application/json" }));

app.post("/webhook", async (req, res) => {
  try {
    // 先验签，再把原始 JSON 解析成可信事件对象。
    const event = await client.webhooks.unwrap(req.body, req.headers);
    const responseId = event.data?.id;

    // 没有关联 ID 时无法更新对应任务，先拒绝这个不完整事件。
    if (!responseId) {
      res.status(400).send("missing response id");
      return;
    }

    switch (event.type) {
      case "response.completed":
        // 完成分支才读取或保存最终响应结果。
        await saveResponseState(responseId, "completed");
        break;
      case "response.cancelled":
        // 取消是明确终态，不要继续显示为等待完成。
        await saveResponseState(responseId, "cancelled");
        break;
      case "response.failed":
        // 失败保留关联 ID，交给业务层记录和处理。
        await saveResponseState(responseId, "failed");
        break;
      default:
        // 新事件不能默认当作成功，避免未来扩展误写业务状态。
        console.info("ignored webhook event", event.type, responseId);
    }

    res.sendStatus(200);
  } catch (error) {
    // 签名错误不应进入任何业务状态分支。
    if (error instanceof OpenAI.InvalidWebhookSignatureError) {
      res.status(400).send("invalid signature");
      return;
    }
    res.sendStatus(500);
  }
});

示例里的 saveResponseState 代表你的数据库写入函数。实际项目中应该让它具备幂等性：同一个事件再次到达时，不重复生成业务结果，也不把已经完成的记录改回取消或失败。

幂等键怎么选，才能避免重复落库

事件自身的 id 适合去重投递，data.id 适合关联同一个后台响应。两者可以同时保存：前者回答“这条通知是否处理过”，后者回答“它属于哪条业务任务”。如果本地任务只保存 response ID，至少也要在更新时检查当前状态，避免晚到的重复通知覆盖更终态。

async function dispatchVerifiedEvent(event) {
  // 事件 ID 用来挡住同一条 webhook 的重复投递。
  if (await eventAlreadyHandled(event.id)) {
    return;
  }

  const responseId = event.data?.id;
  if (!responseId) {
    throw new Error("webhook data.id is required");
  }

  // 只允许明确的三类终态进入状态更新。
  const stateByType = {
    "response.completed": "completed",
    "response.cancelled": "cancelled",
    "response.failed": "failed",
  };
  const nextState = stateByType[event.type];
  if (!nextState) {
    return;
  }

  await saveResponseState(responseId, nextState);
  await markEventHandled(event.id);
}

状态表的具体字段可以按业务命名，但建议把“已取消”和“已失败”保留下来。它们都不是“成功”，却提供了完全不同的运营含义：一个可能是主动终止，一个表示处理没有完成。

常见问题

三个事件都带 data.id，为什么不能统一当成功回调？

因为 data.id 只用于标识对应 response；真正表达终态的是 type。统一当成功会让取消和失败任务进入错误的业务状态。

response.failed 的事件里一定有详细错误信息吗？

事件参考明确展示的是关联响应 ID。需要更多上下文时，应按官方接口和你的业务记录继续处理，不要假设 webhook 外壳一定携带完整错误正文。

可以先 JSON.parse，再调用 unwrap 吗？

不建议。官方 SDK 的验签方法需要原始请求体；先解析再重新序列化可能改变字节内容。保留原始文本，直接交给 unwrap 更稳妥。

未知事件要怎么处理？

记录类型和关联 ID，返回可接受的 HTTP 响应，但不要把未知事件映射成 completed。这样未来新增事件时不会悄悄污染业务状态。

最后的判断清单

• 是否先用原始 body 完成签名校验？
• 是否使用 event.type 而不是 data.id 判断终态？
• 是否把 completed、cancelled、failed 分别落库？
• 是否同时保存 event.id 和 data.id 以支持去重与关联？
• 是否对未知事件采取保守分支？

只要这五项都成立，OpenAI webhook 的三状态分派就不会因为 JSON 外壳相似而把取消、失败误报成完成。