Webhooks — TokSpan ドキュメント

利用可能なイベント

イベント	トリガー	推奨アクション
`spending.alert`	月間利用額が予算の 50%、80%、90%、100% に到達	財務に通知；100% でキーが自動無効化
`key.disabled`	API キーが無効化（予算上限到達、手動、または漏洩）	オンコールに警告；バックアップキーに切り替え
`rate_limit.warning`	使用量が RPM または TPM 制限の 80% に到達	クライアントをスロットル；制限引き上げをリクエスト
`system.incident`	サービス低下または停止を検知	必要に応じて手動フェイルオーバーを有効化

設定

api.tokspan.com/dashboard でダッシュボードにログインします
設定 → Webhooks に移動します
エンドポイントを追加 をクリックし、HTTPS URL を入力します
サブスクライブするイベントを選択します
署名シークレット（whsec_ で始まります）をコピーします — ペイロードの検証に必要です

署名は必ず検証してください。誰でも Webhook エンドポイントに HTTP リクエストを送信できます。X-TokSpan-Signature ヘッダーには、シークレットを使用したペイロードの HMAC-SHA256 署名が含まれています。処理前に必ず検証してください。

署名検証

各 Webhook 配信には、生のリクエストボディの HMAC-SHA256 16進ダイジェストを含む X-TokSpan-Signature ヘッダーが含まれます：

import hmac
import hashlib
import json

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook endpoint handler:
def handle_webhook(request):
    signature = request.headers.get("X-TokSpan-Signature", "")
    if not verify_webhook_signature(request.body, signature, "whsec_your_secret"):
        return 401, "Invalid signature"

    event = json.loads(request.body)
    print(f"Received event: {event['type']}")
    return 200, "OK"

ペイロード形式

すべての Webhook ペイロードは以下の構造に従います：

json — Example: spending.alert
{
  "type": "spending.alert",
  "created": 1700000000,
  "data": {
    "api_key_id": "key_abc123",
    "api_key_name": "production-backend",
    "threshold_pct": 80,
    "monthly_budget": 500.00,
    "current_spend": 400.00,
    "currency": "USD"
  }
}

配信とリトライ

タイムアウト：エンドポイントは 10 秒以内に 2xx ステータスで応答する必要があります
リトライ：失敗した配信は指数バックオフでリトライされます：5秒 → 30秒 → 5分 → 30分 → 1時間。5回失敗すると配信は破棄されます
順序: イベントは順不同で到着する可能性があります。到着順ではなく created タイムスタンプを使用してください。
冪等性: 同じイベントが複数回配信される可能性があります。重複排除には id を使用してください。