主导航

遗留 API

Webhooks

使用 Webhook 从 OpenAI API 接收实时更新。

OpenAI Webhook 允许您接收有关 API 事件的实时通知,例如批量任务完成、后台响应生成或微调作业结束。Webhook 会发送至您控制的 HTTP 端点,并遵循 Standard Webhooks 规范。Webhook 事件的完整列表可以在 API 参考手册中找到。

Webhook 事件 API 参考

查看 Webhook 事件的完整列表。

以下是一些能够接收 OpenAI Webhook 的简单服务器示例,专门针对 response.completed 事件。

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 仪表板中设置一个订阅了 response.completed 的 Webhook 端点,然后发起一个 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 签名最简单的方法是使用官方 OpenAI SDK 辅助工具中的 unwrap() 方法:

使用 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 规范中的描述自行实现签名验证。

如果您丢失或不慎泄露了签名密钥,可以通过轮换签名密钥来生成一个新的。

© . This website operates independently and is not affiliated with or endorsed by OpenAI, Inc. All brand names, logos, and trademarks are the property of their respective owners.