Funciones Avanzadas

Webhooks

Recibe callbacks HTTP en tiempo real para eventos clave: umbrales de gasto, cambios de estado de claves API, advertencias de límites de tasa e incidentes del sistema.

Eventos Disponibles

EventoActivadorAcción Recomendada
spending.alertEl gasto mensual alcanza el 50%, 80%, 90%, 100% del presupuestoNotificar a finanzas; al 100%, la clave se deshabilita automáticamente
key.disabledClave API deshabilitada (límite de presupuesto alcanzado, manual o comprometida)Alertar al equipo de guardia; cambiar a clave de respaldo
rate_limit.warningEl uso alcanza el 80% del límite de RPM o TPMRegular clientes; solicitar aumento de límite
system.incidentDegradación del servicio o caída detectadaActivar conmutación manual si es necesario

Configuración

  1. Inicie sesión en el Panel en api.tokspan.com/dashboard
  2. Navegue a Configuración → Webhooks
  3. Haga clic en Agregar Endpoint e ingrese su URL HTTPS
  4. Seleccione a qué eventos suscribirse
  5. Copie el secreto de firma (comienza con whsec_) — lo necesitará para verificar los payloads
Verifique siempre las firmas. Cualquiera puede enviar solicitudes HTTP a su endpoint de webhook. El header X-TokSpan-Signature contiene una firma HMAC-SHA256 del payload usando su secreto. Valide siempre antes de procesar.

Verificación de Firmas

Cada entrega de webhook incluye un header X-TokSpan-Signature con el resumen hexadecimal HMAC-SHA256 del cuerpo crudo de la solicitud:

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"

Formato del Payload

Todos los payloads de webhook siguen esta estructura:

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"
  }
}

Entrega y Reintentos

  • Timeout: Su endpoint debe responder dentro de 10 segundos con un estado 2xx
  • Reintentos: Las entregas fallidas se reintentan con backoff exponencial: 5s → 30s → 5min → 30min → 1h. Después de 5 fallos, la entrega se descarta
  • Orden: Los eventos pueden llegar fuera de orden. Use la marca de tiempo created, no el orden de llegada
  • Idempotencia: El mismo evento puede entregarse más de una vez. Use id para la deduplicación