English
主导航

旧版 API

Webhooks

使用 webhook 接收来自 OpenAI API 的实时更新。

OpenAI webhooks 允许你接收关于 API 中事件的实时通知,例如批量任务完成、后台响应生成或微调任务结束。Webhook 将按照 Standard Webhooks 规范。完整的 webhook 事件列表可在 API 参考.

Webhook 事件的 API 参考

查看 webhook 事件的完整列表。

以下是一些能够接收来自 OpenAI 的 webhook 的简单服务器示例,专门用于 response.completed event.

Webhook 服务器
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import os
from openai import OpenAI, InvalidWebhookSignatureError
from flask import Flask, request, Response

app = Flask(__name__)
client = OpenAI(webhook_secret=os.environ["OPENAI_WEBHOOK_SECRET"])

@app.route("/webhook", methods=["POST"])
def webhook():
    try:
        # with webhook_secret set above, unwrap will raise an error if the signature is invalid
        event = client.webhooks.unwrap(request.data, request.headers)

        if event.type == "response.completed":
            response_id = event.data.id
            response = client.responses.retrieve(response_id)
            print("Response output:", response.output_text)

        return Response(status=200)
    except InvalidWebhookSignatureError as e:
        print("Invalid signature", e)
        return Response("Invalid signature", status=400)

if __name__ == "__main__":
    app.run(port=8000)

要查看类似于此的 webhook 实际运行情况,你可以在 OpenAI 仪表板中设置一个 webhook 端点,并订阅 response.completed, 然后发起 API 请求至 在后台模式下生成响应.

你还可以使用来自以下位置的样本数据触发测试事件 webhook 设置页面.

生成后台响应
1
2
3
4
5
6
7
8
9
10
11
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
  model="gpt-5.5",
  input="Write a very long novel about otters in space.",
  background=True,
)

print(resp.status)

在本指南中,你将学习如何在仪表板中创建 webhook 端点,设置服务端代码来处理它们,并验证入站请求是否确实来自 OpenAI。

创建 webhook 端点

要开始在您的服务器上接收 webhook 请求,请登录控制面板并 打开 webhook 设置页面。Webhook 按项目进行配置。

点击“创建”按钮以创建新的 webhook 端点。您将配置以下三项内容:

  • 端点名称(仅供您参考)。
  • 您控制的一台服务器的公开 URL。
  • 一个或多个要订阅的事件类型。当这些事件发生时,OpenAI 将向指定的 URL 发送 HTTP POST 请求。
webhook endpoint edit dialog

创建新 webhook 后,您将收到一个签名密钥,用于在服务器端验证传入的 webhook 请求。请保存此值以备后用,因为之后您将无法再次查看它。

创建 webhook 端点后,接下来您需要设置一个服务器端点来处理传入的事件载荷。

在服务器上处理 webhook 请求

当您订阅的事件发生时,您的 webhook URL 将收到如下 HTTP POST 请求:

POST https://yourserver.com/webhook
user-agent: OpenAI/1.0 (+https://platform.openai.com/docs/webhooks)
content-type: application/json
webhook-id: wh_685342e6c53c8190a1be43f081506c52
webhook-timestamp: 1750287078
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{
  "object": "event",
  "id": "evt_685343a1381c819085d44c354e1b330e",
  "type": "response.completed",
  "created_at": 1750287018,
  "data": { "id": "resp_abc123" }
}

您的端点应快速响应这些传入的 HTTP 请求,并返回一个成功(2xx) 状态码,以指示已成功接收。为避免超时,我们建议将任何非简单的处理工作卸载到后台工作器,以便端点能够立即做出响应。如果端点未返回成功(2xx) 状态码,或者在几秒钟内未响应,webhook 请求将被重试。OpenAI 将以指数退避方式继续尝试投递,最长可达 72 小时。请注意, 3xx 重定向将不会被跟随;它们会被视为失败,因此应当更新您的端点以使用最终目标 URL。

在极少数情况下,由于内部系统问题,OpenAI 可能会投递同一 webhook 事件的重复副本。您可以使用 webhook-id 标头作为幂等键进行去重。

在本地测试 Webhook

测试 Webhook 需要一个公网可访问的 URL。这可能会给开发带来不便,因为您的本地开发环境通常不会对公网开放。以下是一些可能有帮助的解决方案:

验证 Webhook 签名

虽然您无需任何验证即可接收来自 OpenAI 的 Webhook 事件并处理结果,但您应该验证传入请求是否确实来自 OpenAI,尤其是当您的 Webhook 会在后端执行任何操作时。与 Webhook 请求一同发送的请求头包含一些信息,这些信息可以与 Webhook 密钥结合使用,以验证该 Webhook 是否源自 OpenAI。

当您在 OpenAI 仪表板中创建 Webhook 端点时,系统会提供一个签名密钥,您应将其作为环境变量在您的服务器上可用:

export OPENAI_WEBHOOK_SECRET="<your secret here>"

验证 Webhook 签名最简单的方法是使用 unwrap() 官方 OpenAI SDK 助手中的方法:

使用 OpenAI SDK 进行签名验证
1
2
3
4
5
client = OpenAI()
webhook_secret = os.environ["OPENAI_WEBHOOK_SECRET"]

# will raise if the signature is invalid
event = client.webhooks.unwrap(request.data, request.headers, secret=webhook_secret)

也可以使用以下方式验证签名 Standard Webhooks 库:

使用 Standard Webhooks 库进行签名验证
1
2
3
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);

或者,如有需要,您可以按照 Standard Webhooks 规范中的说明,自行实现签名验证

如果您的签名密钥丢失或意外泄露,您可以通过 轮换签名密钥来生成一个新的.