進階功能

Webhooks

接收關鍵事件的即時 HTTP 回呼：消費閾值、API 金鑰狀態變更、速率限制警告及系統事件。

可用事件

事件觸發條件建議動作
spending.alert每月支出達到預算的 50%、80%、90%、100%通知財務部門；達到 100% 時，金鑰自動停用
key.disabledAPI 金鑰已停用（預算上限觸發、手動或遭入侵）通知值班人員；切換至備援金鑰
rate_limit.warning用量達到 RPM 或 TPM 限制的 80%對用戶端限流；請求提高限制
system.incident偵測到服務降級或中斷必要時啟動手動容錯移轉

設定

  1. 登入儀表板，網址為api.tokspan.com/dashboard
  2. 前往設定 → Webhooks
  3. 點擊新增端點並輸入您的 HTTPS URL
  4. 選擇要訂閱的事件
  5. 複製簽章密鑰（以 whsec_ 開頭）— 您需要此密鑰來驗證酬載
務必驗證簽章。任何人都可以向您的 Webhook 端點發送 HTTP 請求。X-TokSpan-Signature 標頭包含使用您的密鑰對酬載進行 HMAC-SHA256 簽章的結果。請務必在處理前進行驗證。

簽章驗證

每個 Webhook 傳遞都包含一個 X-TokSpan-Signature 標頭，內含原始請求主體的 HMAC-SHA256 十六進位摘要：

python
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 進行去重複處理