Webhooks

The Webhooks view lets you configure webhook endpoints to receive notifications when quota thresholds are reached.

Overview

The Webhooks feature enables:

• Quota threshold alerts at 80% and 100% usage
• HMAC-SHA256 signed payloads for security
• Automatic deduplication per billing period
• Auto-disable after 5 consecutive delivery failures

Webhook Management

Adding a Webhook

1. Navigate to the Webhooks view
2. Click Add Webhook
3. Enter the webhook URL (must be HTTPS)
4. Save

Webhook Requirements

Requirement	Details
Protocol	HTTPS only (HTTP rejected)
IP Range	Public IPs only (private/loopback rejected)
Response	Must return 2xx within timeout

Payload Format

{
  "event": "quota.warning",
  "threshold": 80,
  "tenant_id": "tenant_abc123",
  "billing_period": "2026-03",
  "current_usage_mb": 820,
  "quota_mb": 1024,
  "timestamp": "2026-03-09T10:30:00.000Z"
}

Events

Event	Threshold	Description
quota.warning	80%	Approaching quota limit
quota.exceeded	100%	Quota limit reached

Security

HMAC Verification

All webhook payloads are signed with HMAC-SHA256 using a per-tenant secret:

X-Webhook-Signature: sha256=<hmac_hex>
X-Webhook-Timestamp: <unix_timestamp>

Verify the signature on your server to ensure payload authenticity.

Replay Protection

Check the X-Webhook-Timestamp header. Reject payloads older than 5 minutes to prevent replay attacks.

Failure Handling

• Webhooks that fail to deliver are retried
• After 5 consecutive failures, the webhook is auto-disabled
• Re-enable from the Webhooks view after fixing the endpoint

API Access

Webhooks are also accessible via:

• REST API: GET/POST/DELETE /api/webhooks

Next Steps

• Dashboard - Monitor usage and quotas
• Analytics - View detailed usage analytics