Advanced Features

Webhooks

Receive real-time HTTP callbacks for key events: spending thresholds, API key status changes, rate limit warnings, and system incidents.

Available Events

EventTriggerRecommended Action
spending.alertMonthly spend reaches 50%, 80%, 90%, 100% of budgetNotify finance; at 100%, key is auto-disabled
key.disabledAPI key disabled (budget cap hit, manual, or compromised)Alert on-call; switch to backup key
rate_limit.warningUsage reaches 80% of RPM or TPM limitThrottle clients; request limit increase
system.incidentService degradation or outage detectedActivate manual failover if needed

Setup

  1. Log in to the Dashboard at api.onerouter.app/dashboard
  2. Navigate to Settings → Webhooks
  3. Click Add Endpoint and enter your HTTPS URL
  4. Select which events to subscribe to
  5. Copy the signing secret (starts with whsec_) — you'll need this to verify payloads
Always verify signatures. Anyone can send HTTP requests to your webhook endpoint. The X-OneRouter-Signature header contains an HMAC-SHA256 signature of the payload using your secret. Always validate before processing.

Signature Verification

Each webhook delivery includes an X-OneRouter-Signature header with the HMAC-SHA256 hex digest of the raw request body:

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-OneRouter-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 Format

All webhook payloads follow this structure:

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

Delivery & Retries

  • Timeout: Your endpoint must respond within 10 seconds with a 2xx status
  • Retries: Failed deliveries are retried with exponential backoff: 5s → 30s → 5min → 30min → 1h. After 5 failures, the delivery is dropped
  • Ordering: Events may arrive out of order. Use the created timestamp, not arrival order
  • Idempotency: The same event may be delivered more than once. Use id for deduplication