如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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 密钥,将权限设为受限,再将安全权限设为读取(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 错误 采用退避策略重试,并限制重试次数。保留事件,以便后续处理或调查。