Skip to main content

网络钩子

SecureAI 可以将安全和平台事件实时推送到您自己的 HTTP 端点 - Prompt Shield 阻止、金丝雀泄漏、DLP/PII 事件、API 限制事件和模型故障转移。每次交付均使用 HMAC-SHA256 签名进行签名,因此您可以验证它来自 SecureAI 并且未被篡改或重播。 Webhook 端点由管理员在 Admin → Webhooks(API 基础 /api/admin/webhooks)中进行管理。

管理端点

创建时输入:url、description、events[](请参阅事件)和enabled。签名秘密 (whsec_...) 仅在创建和旋转时显示 - 安全存储它;您无法再次检索它。 端点 url 经过 SSRF 验证:仅接受 http(s),私有/环回/本地链路主机将被拒绝,除非实例与 WEBHOOKS_ALLOW_PRIVATE=true 一起运行(自托管接收器通常需要此)。

交付格式

每个交付都是一个带有 JSON 正文的 HTTP POST:
还有这些标题: 您的端点应返回任何 2xx 状态以确认传送。

验证签名

通过 `${t}.${rawBody}` using your signing secret and compare it to the v1 value. Reject the delivery if it doesn’t match, or if t 重新计算 HMAC 超出了容差窗口(重放保护)。 根据原始请求正文进行验证 — 首先解析并重新序列化 JSON 将更改字节并破坏签名。

Node.js(Express)

Python(烧瓶)

可靠性

  • 重试: 最多 3 次尝试,每次有 0 秒/10 秒/60 秒回退,每次 5 秒超时。任何2xx确认。
  • **自动禁用:**连续 20 次传送失败后,端点将自动禁用;管理员重新启用它(这也会重置失败计数器)。
  • 至少一次: 交付可能会重复 — 在 X-SecureAI-Delivery(或有效负载 id)上进行重复数据删除。
  • 即发即忘: Webhook 传递永远不会阻止或延迟原始 API 请求。

相关