API Webhooks

Webhooks allow you to receive real-time HTTP notifications when events occur on your servers.

Setting Up Webhooks

Create a Webhook

POST /v1/webhooks
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/cdhosting",
  "events": ["server.started", "server.stopped", "server.error"],
  "secret": "your_webhook_secret"
}

POST /v1/webhooks
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/cdhosting",
  "events": ["server.started", "server.stopped", "server.error"],
  "secret": "your_webhook_secret"
}

Available Events

Webhook Payload

{
  "id": "evt_abc123",
  "type": "server.started",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "server_id": "srv_abc123",
    "name": "production-web-01",
    "status": "running",
    "ip": "192.168.1.100"
  }
}

{
  "id": "evt_abc123",
  "type": "server.started",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "server_id": "srv_abc123",
    "name": "production-web-01",
    "status": "running",
    "ip": "192.168.1.100"
  }
}

Verifying Signatures

const crypto = require('crypto');

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

const crypto = require('crypto');

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

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failed attempts, the webhook is disabled and you'll receive an email notification.