Skip to main content

Webhook

SecureAI は、プロンプト シールド ブロック、カナリア リーク、DLP/PII インシデント、API 制限イベント、モデル フェイルオーバーなど、セキュリティ イベントとプラットフォーム イベントを独自の HTTP エンドポイントにリアルタイムでプッシュできます。すべての配信は HMAC-SHA256 署名で署名されるため、SecureAI から送信されたものであり、改ざんまたは再生されていないことを確認できます。 Webhook エンドポイントは、Admin → Webhook (API ベース /api/admin/webhooks) で管理者によって管理されます。

エンドポイントの管理

作成時の入力: urldescriptionevents[] (イベント を参照)、および 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 (高速)

Python (フラスコ)

信頼性

  • 再試行: 0 秒 / 10 秒 / 60 秒のバックオフで最大 3 回の試行、それぞれ 5 秒のタイムアウト。 2xx はすべて承認します。
  • 自動無効化: 20 回連続して配信に失敗すると、エンドポイントは自動的に無効になります。管理者がそれを再度有効にします (失敗カウンターもリセットされます)。
  • 少なくとも 1 回: 配信は繰り返される場合があります。X-SecureAI-Delivery (またはペイロード id) で重複を排除します。
  • ファイアアンドフォーゲット: Webhook 配信は、発信元の API リクエストをブロックしたり遅延したりすることはありません。

関連