使用安全 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 错误 |
采用退避策略重试,并限制重试次数。保留事件,以便后续处理或调查。 |