OpenAI Webhooks 怎么用？

官方资料（2026-10-30 核对）：Webhooks guide · Webhook event reference · OpenAI Node SDK Webhooks · OpenAI Python SDK verification

OpenAI Webhooks 解决什么问题？

Webhook 是 OpenAI 在订阅事件发生时向你的公开服务器发送的 HTTP POST。它适合后台 Response 完成、失败或取消等异步状态通知，避免应用持续高频轮询。事件通常只包含事件类型和资源 ID；业务系统仍应使用自己的服务端凭证查询资源的最终状态和完整结果。

单个长任务的创建、轮询和取消见 Background Mode 教程；增量展示见 API Streaming；模型请求外部动作见 Function Calling。

第一步：在 Dashboard 创建项目 Webhook 端点

1. 进入 OpenAI Dashboard 当前项目的 Webhook 设置。
2. 填写只供管理识别的端点名称。
3. 填写服务器可公开访问的最终 HTTPS URL，例如 https://app.example.com/api/openai/webhook。
4. 只选择业务真正处理的事件类型，减少无关流量和日志。
5. 创建后立即把 signing secret 写入生产 Secret Manager 或部署平台环境变量。

Dashboard 支持发送样例测试事件。测试能验证网络和处理分支，但样例成功不代表生产幂等、数据库事务、队列积压和密钥轮换已经正确。

第二步：保留原始请求体，再调用官方 SDK 验签

请求包含 webhook-id、webhook-timestamp 和 webhook-signature。签名覆盖原始请求体；JSON 中间件解析后再序列化可能改变字节，因此必须先读取原始文本或字节。

import OpenAI, { InvalidWebhookSignatureError } from "openai";

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

export async function POST(request) {
  const rawBody = await request.text();

  let event;
  try {
    event = await client.webhooks.unwrap(rawBody, request.headers);
  } catch (error) {
    if (error instanceof InvalidWebhookSignatureError) {
      return new Response("invalid signature", { status: 400 });
    }
    return new Response("invalid webhook", { status: 400 });
  }

  // 只有这里之后，event 和 webhook-id 才可以被信任
  const deliveryId = request.headers.get("webhook-id");
  await storeVerifiedDeliveryAtomically({
    deliveryId,
    eventId: event.id,
    eventType: event.type,
    resourceId: event.data?.id,
    rawBody
  });

  return new Response("ok", { status: 200 });
}

unwrap() 会先验证再解析。若要自己做 Schema 校验或路由，可以先 await client.webhooks.verifySignature(rawBody, headers)，成功后再 JSON.parse。Node SDK 当前默认时间戳容差为 300 秒；验签依赖服务器时钟，必须保持 NTP 同步。不要为了“修复偶发失败”把容差无限放大。

Express、Next.js 与 Serverless 最容易错在哪里？

验签失败时先检查 Secret 是否属于当前端点和环境、正文是否被解析或压缩、三个头是否被代理保留，以及服务器时钟。不要记录完整签名 Secret 或用户敏感正文来排错。

第三步：用 webhook-id 做持久去重

官方明确说明少数情况下同一事件可能重复投递，并建议把 webhook-id 作为幂等键。签名验真不等于 exactly-once：同一份合法请求可以多次通过验签。

BEGIN;

INSERT INTO webhook_inbox
  (endpoint, delivery_id, event_id, event_type, resource_id, status)
VALUES
  ('openai-main', :webhook_id, :event_id, :event_type, :resource_id, 'queued')
ON CONFLICT (endpoint, delivery_id) DO NOTHING;

-- 只有新记录才写入 outbox/queue job
INSERT INTO outbox (...) SELECT ... WHERE inserted = true;

COMMIT;

• 唯一键至少包含端点或环境与 webhook-id，避免测试和生产互相碰撞。
• “记录已处理”与业务副作用最好位于同一事务或可靠 outbox 流程。
• 重复投递已经成功处理时返回 2xx，不要故意返回错误让它继续重试。
• 资源终态更新也要幂等，例如按 response ID 只允许状态单向进入终态。
• 不要仅用进程内 Set 或短 TTL 缓存；多实例和重启后会失效。

第四步：先可靠入队，再在数秒内返回 2xx

OpenAI 建议端点快速返回成功状态，并把非平凡处理交给后台 Worker。正确边界不是“收到请求立即 200”，而是“验签成功，且事件已可靠落库或入队后立即 200”。

1. 读取原始正文和签名头。
2. 验签并解析事件。
3. 原子写入幂等收件箱与 outbox/队列。
4. 返回 200 或其他 2xx。
5. Worker 获取任务，按事件类型查询资源并执行幂等业务。

不要在接收器中同步下载大结果、调用多个外部系统、发送邮件或等待人工流程。这些操作会超过数秒，导致 OpenAI 认为失败并重投。反过来，在未落库前先 200，进程随后崩溃会造成无法自动补投的业务丢失。

第五步：按事件类型路由，再查询真实资源终态

当前参考列出 Response completed、failed、cancelled 等事件。事件的 data.id 指向资源；Worker 应使用正确 Project 的服务端 API Key 查询完整对象，并依据返回的真实状态更新业务。

async function processWebhook(job) {
  switch (job.eventType) {
    case "response.completed":
    case "response.failed":
    case "response.cancelled": {
      const response = await client.responses.retrieve(job.resourceId);
      await applyResponseStateIdempotently(response);
      break;
    }
    default:
      await markIgnoredButAcknowledged(job.deliveryId);
  }
}

• 事件类型使用 allowlist；未知新类型记录后安全忽略，不要默认执行副作用。
• 终态查询失败按 429、5xx、网络错误和权限错误分类，使用 Worker 自己的有限重试。
• 资源归属要绑定用户、Project 和内部任务，不能只凭传入 ID 越权读取。
• 处理完成记录 delivery ID、event ID、资源 ID、耗时与结果；敏感正文脱敏。

失败、重试和 3xx 应怎样处理？

如果端点未在数秒内返回 2xx，OpenAI 会指数退避重试，当前最长持续 72 小时。3xx 不会被跟随，也被视为失败，因此端点 URL 必须直接指向最终处理地址。

72 小时是投递尝试窗口，不是事件必须在 72 小时内完成全部业务的承诺。业务系统应监控最后成功接收时间、失败率、重复率、队列积压和最老任务年龄，并设置补偿查询。

轮换 Secret 与多环境部署

• 开发、预览和生产使用不同端点与 Secret，不让测试事件进入生产数据库。
• 环境变量命名清楚，并在部署后确认对应端点，不输出 Secret 值。
• 泄露或丢失后在 Dashboard 轮换 Secret，并以短暂双验证窗口完成无停机切换；具体能力以当前 Dashboard 为准。
• 先让新版本能验证新 Secret，再切换发送端，最后移除旧 Secret。
• 变更期间监控验签失败，避免时钟漂移或代理改写被误判为密钥问题。

本地测试与上线验收

1. 使用公开 HTTPS 隧道或云开发环境，把最终 URL 配到测试项目。
2. 从 Dashboard 发送样例事件，确认原始正文、三个签名头和 2xx。
3. 重复发送同一已验签 payload，验证唯一约束只产生一个业务任务。
4. 故意修改正文、签名和时间戳，确保 4xx 且无副作用。
5. 让队列 Worker 暂停，确认接收器仍能可靠入队并快速 2xx。
6. 模拟数据库失败，确认端点非 2xx，恢复后重复投递只处理一次。
7. 使用真实 background Response 验证 completed/failed/cancelled 分支与资源查询。
8. 检查日志、告警与 Dashboard，不包含 API Key、签名 Secret 或敏感正文。

Webhook 不替代 API 故障分类。Worker 查询资源遇到超时、500 或 503 时，继续按 API 5xx 与超时指南处理；遇到 429 看 速率限制指南。

上线前检查清单

• Dashboard 使用最终 HTTPS URL，不依赖 3xx。
• signing secret 存放在服务端 Secret Manager，未进入 Git 和前端。
• Webhook 路由保留原始正文和三个签名头。
• 官方 SDK 验签在 JSON 解析和业务逻辑之前完成。
• 服务器时钟同步，时间戳容差没有被任意放大。
• webhook-id 有跨实例持久唯一约束。
• 验签与可靠持久化成功后数秒内返回 2xx。
• Worker 按资源 ID 查询真实终态，所有副作用幂等。
• 重复、乱序、延迟、未知事件、队列失败与 Secret 轮换均有测试。
• 监控接收成功率、重复率、积压、最老任务和补偿轮询。

常见问题

本文核对日期为 2026-10-30。OpenAI 事件类型、SDK 方法和投递策略可能调整，上线前请再次读取官方 Webhooks 指南与当前 SDK 文档。