Webhook Documentation

Receive real-time push events when budget thresholds are triggered or alerts are generated.

Supported Event Types

threshold_triggered

Fired when usage exceeds a configured threshold percentage.

{
  "id": "wd_abc123",
  "type": "threshold_triggered",
  "timestamp": 1713618023,
  "data": {
    "project_name": "Production API",
    "metric_type": "cost",
    "current_usage": 85.50,
    "threshold_value": 100,
    "usage_percentage": 85.5,
    "time_window": "monthly",
    "timestamp": "2026-04-21T10:30:45Z"
  }
}

alert_generated

Fired when an alert rule is triggered.

{
  "id": "wd_def456",
  "type": "alert_generated",
  "timestamp": 1713618023,
  "data": {
    "rule_name": "High Error Rate",
    "severity": "high",
    "project": "Production",
    "error_count": 150,
    "timestamp": "2026-04-21T10:30:45Z"
  }
}

usage_update

Periodic usage update (sent hourly).

{
  "id": "wd_ghi789",
  "type": "usage_update",
  "timestamp": 1713618023,
  "data": {
    "period": "hourly",
    "total_requests": 45230,
    "total_cost": 12.45,
    "tokens_in": 1234567,
    "tokens_out": 567890
  }
}

Webhook Security

All webhook requests are signed with HMAC-SHA256. Verify the signature to ensure authenticity.

Headers

X-Webhook-Signature: sha256=hex_encoded_hmac

X-Webhook-Timestamp: unix timestamp

X-Webhook-ID: webhook endpoint ID

Content-Type: application/json

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  const expected = 'sha256=' + hash;
  return crypto.timingSafeEqual(signature, expected);
}

// In your webhook handler
const signature = req.headers['x-webhook-signature'];
const payload = req.rawBody; // Raw request body

if (!verifyWebhook(payload, signature, WEBHOOK_SECRET)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

const event = JSON.parse(payload);
// Process event