Webhooks

Webhooks allow you to receive real-time notifications about events happening in your PerceptOS account. Instead of polling the API, we'll send HTTP POST requests to your specified URL when events occur.

Supported Events

usage.threshold

Triggered when usage reaches 80% of quota

api_key.created

New API key has been generated

api_key.revoked

API key has been revoked

payment.succeeded

Payment processed successfully

plan.upgraded

Account plan has been upgraded

plan.downgraded

Account plan has been downgraded

Webhook Payload

All webhook events are sent as HTTP POST requests with the following structure:

json

{
  "event": "usage.threshold",
  "timestamp": 1704067200,
  "request_id": "evt_abc123",
  "data": {
    "usage_percent": 80,
    "total_quota": 1000000,
    "current_usage": 800000,
    "plan": "pro"
  }
}

Webhook Security

Each webhook request includes security headers to verify authenticity:

X-Webhook-Signature
HMAC-SHA256 signature of the request body
X-Webhook-Timestamp
Unix timestamp of when webhook was sent
X-Webhook-ID
Unique identifier for this webhook delivery

Verifying Signatures

javascript

const crypto = require('crypto');

function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  
  const payload = JSON.stringify(req.body);
  const message = `${timestamp}.${payload}`;
  
  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(message)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Handling Webhooks

Best practices for reliable webhook handling:

1.Return a 200 response immediately, then process asynchronously
2.Use the request_id to deduplicate webhook deliveries
3.Always verify the webhook signature to ensure authenticity
4.Implement exponential backoff if your endpoint is unreliable