如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

安全政策執行通知

將警告與停用通知納入調查與支援流程。

透過安全 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 錯誤 採用退避策略重試,並限制重試次數。保留事件以供後續處理或調查。