如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

Webhook

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

通过 OpenAI 的 webhook,您可以在 API 事件发生时实时收到通知,例如批处理完成、后台响应生成完毕或微调任务结束。OpenAI 遵循 Standard Webhooks 规范,将 webhook 请求发送到您控制的 HTTP 端点。有关 webhook 事件的完整列表,请参阅 API 参考文档。

要接收 API 项目的对齐偏差监控通知,请参阅接收项目安全警报。

要接收有关安全标识符的组织级警告和停用通知,请参阅安全策略执行通知。

有关 Agents API 的会话事件和恢复方式,请参阅会话 webhook。配置 webhook 接收端时,请遵循本页有关端点设置、签名验证和事件投递的说明。

Webhook 事件 API 参考文档

查看 webhook 事件的完整列表。

以下服务器示例以 response.completed 事件为例,展示如何接收 OpenAI 发送的 webhook 请求。

要运行 Ruby 示例,请先使用 gem install openai webrick 安装所需的依赖项,然后设置 OPENAI_API_KEY 和 OPENAI_WEBHOOK_SECRET。

Webhook 服务器
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 设置页面上使用示例数据触发测试事件。

生成后台响应
from openai import OpenAI

client = OpenAI()

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

print(resp.status)

本指南介绍如何在控制台中创建 webhook 端点、编写服务端代码来处理 webhook 请求,以及验证收到的请求是否来自 OpenAI。

创建 webhook 端点

要让服务器开始接收项目的 webhook 请求,请登录控制台并打开 webhook 设置页面。本节介绍项目级端点的设置方法。有关组织级安全事件,请参阅安全策略执行通知。

点击“创建”按钮,新建 webhook 端点。您需要配置以下三项:

  • 端点名称,仅供您自己识别。
  • 指向您控制的服务器的公网 URL。
  • 要订阅的一种或多种事件类型。这些事件发生时,OpenAI 会向指定的 URL 发送 HTTP POST 请求。
用于编辑 webhook 端点的对话框

创建 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),或未在几秒内响应,OpenAI 会重新发送 webhook 请求。OpenAI 会按指数退避策略持续重试,最长可达 72 小时。OpenAI 会将 3xx 重定向视为投递失败,不会跟随重定向。遇到这种情况,请将端点的 URL 更新为最终目标 URL。

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

在本地测试 webhook

测试 webhook 需要一个可从公网访问的 URL。本地开发环境通常不对公网开放,这会给测试带来困难。您可以尝试以下方法:

验证 webhook 签名

即使不做验证,您也能接收 OpenAI 的 webhook 事件并处理结果,但仍应验证收到的请求确实来自 OpenAI,尤其是当 webhook 会触发后端操作时。您可以结合 webhook 签名密钥和请求头中的信息,验证请求是否来自 OpenAI。

在 OpenAI 控制台中创建 webhook 端点时,您会获得一个签名密钥。请在服务器上将其设置为环境变量:

export OPENAI_WEBHOOK_SECRET="<your secret here>"

验证 webhook 签名最简单的方法是使用 OpenAI 官方 SDK 提供的 unwrap() 方法:

使用 OpenAI SDK 验证签名
import os

from flask import request
from openai import OpenAI

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 库验证签名
$webhook_secret = getenv("OPENAI_WEBHOOK_SECRET");
$wh = new \StandardWebhooks\Webhook($webhook_secret);
$wh->verify($webhook_payload, $webhook_headers);

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

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