Расширенные возможности

Webhooks

Получайте HTTP-уведомления в реальном времени о ключевых событиях: пороги расходов, изменения статуса API-ключей, предупреждения о лимитах и системные инциденты.

Доступные события

СобытиеТриггерРекомендуемое действие
spending.alertМесячные расходы достигают 50%, 80%, 90%, 100% бюджетаУведомить финансовый отдел; при 100% ключ автоматически отключается
key.disabledКлюч API отключён (достигнут лимит бюджета, вручную или скомпрометирован)Оповестить дежурного; переключиться на резервный ключ
rate_limit.warningИспользование достигает 80% лимита RPM или TPMОграничить клиентов; запросить увеличение лимита
system.incidentОбнаружена деградация сервиса или сбойПри необходимости активировать ручной фейловер

Настройка

  1. Войдите в Панель управления по адресу api.tokspan.com/dashboard
  2. Перейдите в Настройки → Webhooks
  3. Нажмите Добавить endpoint и введите ваш HTTPS URL
  4. Выберите события, на которые хотите подписаться
  5. Скопируйте секрет подписи (начинается с whsec_) — он понадобится для проверки payload
Всегда проверяйте подписи. Любой может отправить HTTP-запрос на ваш endpoint Webhook-а. Заголовок X-TokSpan-Signature содержит HMAC-SHA256 подпись payload с использованием вашего секрета. Всегда проверяйте перед обработкой.

Проверка подписи

Каждая доставка Webhook-а содержит заголовок X-TokSpan-Signature с HMAC-SHA256 hex-дайджестом сырого тела запроса:

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"

Формат payload

Все payload 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"
  }
}

Доставка и повторные попытки

  • Тайм-аут: Ваш endpoint должен ответить в течение 10 секунд со статусом 2xx
  • Повторные попытки: Неудачные доставки повторяются с экспоненциальной задержкой: 5 с → 30 с → 5 мин → 30 мин → 1 ч. После 5 неудач доставка отбрасывается
  • Порядок: События могут поступать не по порядку. Используйте временную метку created, а не порядок получения
  • Идемпотентность: Одно и то же событие может быть доставлено более одного раза. Используйте id для дедупликации