コールバック

署名された冪等のサーバー間イベントと完了した非同期結果を受信します。

コールバック

でコールバック URL を構成します プロファイル → コールバックと非同期結果。 Model Gate は HTTPS を送信します POST 有効なアカウント通知と完了したネイティブ非同期推論リクエストのリクエスト。コールバックの配信は推論処理から独立しており、専用の耐久性のある Model Gate ワーカーキューを通じて実行されます。

コールバック URL とアウトバウンドセキュリティ

パブリックにアクセス可能な HTTPS エンドポイントを使用します。コールバック URL 検証はアウトバウンドのセキュリティ境界です。ループバック、プライベート、リンクローカル、キャリアグレード NAT、ドキュメント/テスト、マルチキャスト、未指定および予約済みの IP 範囲は拒否されます。ホスト名は保存時と配信時に再度検証されます。リダイレクトが再検証されます。コールバックを内部サービスに向けたり、プライベートネットワークにリダイレクトしたりしないでください。

共通イベントエンベロープ

すべてのコールバックは同じエンベロープを使用します。

{
  "event_id": "01J...",
  "event": "account.balance_low",
  "occurred_at": "2026-08-28T07:00:00Z",
  "data": {}
}

event_id 1 つの論理イベントの再試行ごとに安定しています。配信の重複を排除する event_id;ペイロードの残りの部分を比較して ID を推測しないでください。 occurred_at は UTC RFC3339 です。ペイロードは時間の経過とともに追加のフィールドを取得する可能性があるため、コンシューマは未知のフィールドを無視する必要があります。

すべての配信には、同じイベント ID も含まれます。 X-Model-Gate-Event-ID。

イベントカタログ

`account.balance_low`

{
  "event_id": "01J...",
  "event": "account.balance_low",
  "occurred_at": "2026-08-28T07:00:00Z",
  "data": {
    "balance": "10.1234567890",
    "threshold": "20.0000000000",
    "currency": "USD"
  }
}

`key.spend_limit_threshold_reached`

{
  "event_id": "01J...",
  "event": "key.spend_limit_threshold_reached",
  "occurred_at": "2026-08-28T07:00:00Z",
  "data": {
    "key_id": "KEY_PUBLIC_ID",
    "key_name": "Bank integration",
    "usage": "80.1234567890",
    "spend_limit": "100.0000000000",
    "threshold_percent": 80,
    "currency": "USD"
  }
}

`group.spend_limit_threshold_reached`

ペイロードは使用します group_id、 group_name、正確な 10 進数 usage、正確な 10 進数 spend_limit、整数 threshold_percent、そして currency = "USD"。

`request.completed`

{
  "event_id": "01J...",
  "event": "request.completed",
  "occurred_at": "2026-08-28T07:00:00.123456Z",
  "data": {
    "request_id": "01J...",
    "status": "completed",
    "response_status": 200,
    "response": {"id":"msg_...","type":"message"}
  }
}

response_status アップストリーム HTTP ステータスが存在しない場合は null 可能です。失敗/キャンセル/期限切れの非同期結果には次のものが含まれる場合があります。 data.error。

コールバックペイロード内の財務値は正確な 10 進数の文字列です。これらは UI で丸められた表示値ではありません。

しきい値アラートは、監視されている値がしきい値条件を離れた後に再度警告されます。しきい値ワーカーは、推論ホットパスの外側で 1 分に約 1 回条件を評価するため、しきい値コールバックはリアルタイムのミリ秒を超える信号ではありません。

リクエストフォーマット

POST /model-gate/callback HTTP/1.1
Content-Type: application/json
X-Model-Gate-Event-ID: 01J...
X-Model-Gate-Signature: t=1710000000,v1=hex_hmac_sha256

署名の検証

正確な文字列に対して HMAC-SHA256 を計算します。 <timestamp>.<raw_body> プロファイルで生成されたコールバックシークレットを使用します。完全なシークレットは生成またはローテーションされた場合にのみ表示され、保存時には暗号化されて保存されます。 16 進数の署名を一定時間で比較し、受け入れられた再生ウィンドウ外のタイムスタンプを拒否します。 HMAC タイムスタンプは配信試行に固有です。の event_id 再試行しても安定した状態を保ちます。

配信、応答、および再試行

任意のHTTP 2xx 応答はイベントを受け入れます。 HTTP 200 空のボディを使用することをお勧めします。トランスポートエラー、タイムアウト、および 2xx 以外のすべての応答は失敗します。

各イベントには最大でも 合計6回の試行: 最初の試行と 5 回の再試行。失敗した試行 1 ～ 5 の後には、 5秒、30秒、2分、10分、1時間。それぞれの試みには困難があります 15秒 全体的なタイムアウト。 6 回目の試行が失敗すると、イベントは終了状態になります failed さらに自動再試行は行われません。古いワーカークレームは自動的に永続キューに返されます。

応答する前に長時間実行される作業を実行しないでください。署名を検証し、永続化/重複排除します。 event_id、戻る 2xx、非同期的に処理します。

コールバック