透過安全 Webhook 和安全案件讀取 API,你可以將 OpenAI 的安全政策執行通知納入團隊的工作流程。例如,應用程式收到警告時,可以查詢案件詳情、找出受影響的使用者,並建立內部審查工單。
適用情境
你可以透過這項整合:
- 將警告與停用通知轉交給信任與安全團隊或支援團隊。
- 將案件資訊加入調查或支援工單。
- 根據應用程式中安全識別碼與使用者的對應關係,將通知連結至對應的使用者。
本指南以警告通知為例,說明各個處理步驟。你也可以透過同一項整合處理停用通知。
運作方式
OpenAI 發出通知時,應用程式會透過安全 Webhook 收到對應的事件。
| 事件 | 通知 |
|---|---|
safety.warning_issued |
針對組織內某個安全識別碼發出的警告通知。 |
safety.deactivation_issued |
針對組織內某個安全識別碼發出的停用通知。 |
每個事件都包含案件 ID。使用這個 ID 呼叫 GET /v1/safety/cases/{id},即可取得安全識別碼、通知類型和案件建立時間戳記。如果有政策相關的原因說明,回應也會一併傳回。
這些組織層級的通知與專案層級的模型行為偏離預期警示 各自獨立。查詢案件不會變更或撤銷已採取的措施。
整合至應用程式
先設定組織層級的 Webhook 和用於查詢案件的金鑰,再將通知納入審查流程。
設定 Webhook 並接收事件
為每位使用者指定一個固定的安全識別碼,並在應用程式中保留識別碼與使用者的對應關係。請避免在識別碼中加入個人資訊。
在組織的 Webhook 設定中建立組織層級的 Webhook 端點,並訂閱 safety.warning_issued 和 safety.deactivation_issued。
警告通知的結構如下:
{
"id": "evt_example",
"object": "event",
"created_at": 1787659200,
"type": "safety.warning_issued",
"data": {
"id": "C-abc123"
}
}
如需瞭解使用 Webhook 的一般最佳做法,請參閱 Webhook 指南。
事件中的 id 用來識別 Webhook 事件,data.id 則用來識別要查詢的安全案件。
查詢案件
若要查詢案件,請為同一個組織設定 API 金鑰,選擇 Restricted 權限,並將 Safety 設為 Read(api.safety.read)。
透過安全案件讀取 API 查詢案件中繼資料:
curl "https://api.openai.com/v1/safety/cases/C-abc123" \
-H "Authorization: Bearer ${OPENAI_API_KEY}"
查詢成功時,API 會傳回 HTTP 狀態碼 200 和一個案件物件。例如:
{
"id": "C-abc123",
"object": "safety.case",
"created_at": 1787659100,
"entity_identifier": "entity_identifier",
"reason": "cyber_abuse",
"notice": {
"type": "warning"
}
}
entity_identifier 代表受影響的安全識別碼。調查時可參考案件建立時間戳記。如需各欄位的定義,請參閱安全案件 API 參考文件。
將通知納入工作流程
透過 Webhook 接收通知後,即可根據案件中繼資料,以程式將通知轉交給現有的調查或支援系統處理。
疑難排解
| 問題 | 檢查項目 |
|---|---|
| 簽章驗證失敗 | 檢查簽章密鑰,並依照 Webhook 指南的說明保留原始請求主體。 |
查詢傳回 401 |
確認請求包含有效的 API 金鑰。 |
查詢傳回 403 |
確認金鑰具有 api.safety.read 權限。 |
查詢傳回 404 |
請使用 data.id 查詢,避免誤用事件 ID。確認案件與金鑰屬於同一個組織。 |
查詢傳回 429 或暫時性的 5xx 錯誤 |
採用退避策略重試,並限制重試次數。保留事件以供後續處理或調查。 |