如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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-astra",
    input="Write a very long novel about otters in space.",
    background=True,
)

print(resp.status)

本指南說明如何在控制台建立 webhook 端點、設定伺服器端程式碼以處理 webhook 請求,以及驗證收到的請求是否來自 OpenAI。

建立 webhook 端點

若要讓伺服器開始接收專案的 webhook 請求,請登入控制台並開啟 webhook 設定頁面。本節說明如何設定專案端點。如需瞭解組織層級的安全事件,請參閱安全政策執行通知。

按一下「建立」按鈕以新增 webhook 端點。你需要設定以下三個項目:

  • 端點名稱(僅供你辨識)。
  • 指向你所管理之伺服器的公開網址。
  • 要訂閱的一或多種事件類型。這些事件發生時,OpenAI 會向指定網址傳送 HTTP POST 請求。
編輯 webhook 端點的對話方塊

建立 webhook 後,你會收到一組簽章密鑰,可在伺服器端用來驗證收到的 webhook 請求。請立即儲存密鑰以供日後使用,因為之後無法再次查看。

建立 webhook 端點後,接著在伺服器端設定端點,以處理收到的事件酬載。

在伺服器上處理 webhook 請求

當你訂閱的事件發生時,你的 webhook 網址會收到如下的 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" }
}

端點應儘快回傳成功狀態碼(2xx),表示已收到 HTTP 請求。為避免逾時,建議將較繁重的處理工作交由背景工作程序執行,讓端點能立即回應。 如果端點未回傳成功狀態碼(2xx),或未在幾秒內回應,OpenAI 就會重新傳送 webhook 請求。OpenAI 會採用指數退避策略逐步延長重試間隔,最長會持續嘗試傳送 72 小時。OpenAI 會將 3xx 重新導向視為傳送失敗,不會向重新導向的網址重送請求。請將端點網址更新為最終目的地網址。

在極少數情況下,OpenAI 可能因內部系統問題而重複傳送同一個 webhook 事件。你可以使用 webhook-id 標頭作為冪等鍵,避免重複處理事件。

在本機測試 webhook

測試 webhook 需要可從公用網際網路存取的網址。本機開發環境通常不對外開放,因此測試時可能會遇到困難。你可以考慮以下方式:

驗證 webhook 簽章

即使略過驗證,你仍可接收 OpenAI 的 webhook 事件並處理結果,但你應確認收到的請求確實來自 OpenAI,尤其是 webhook 會在後端觸發操作時。你可以搭配使用 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 規格中的說明,自行實作簽章驗證。

如果簽章密鑰遺失或意外外洩,你可以輪替簽章密鑰以產生新的密鑰。