Webhooks API

TL;DR

The Webhooks API lets you receive real-time HTTP POST notifications for session, machine, command, and file events. Create webhooks with POST /webhooks, subscribe to specific event types, verify payloads using HMAC-SHA256 signatures, and test endpoints before going live. Failed deliveries are retried 3 times with exponential backoff.

How do I list webhooks?


GET /webhooks

Response


{
  "data": [
    {
      "id": "hook_abc123",
      "url": "https://example.com/webhook",
      "events": ["machine.offline", "command.failed"],
      "enabled": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

How do I create a webhook?


POST /webhooks

Request Body

Field	Type	Required	Description
`url`	string	Yes	Webhook endpoint URL
`events`	array	Yes	Events to subscribe to
`secret`	string	No	Signing secret
`enabled`	boolean	No	Default: true

Example


curl -X POST https://api.cmdop.com/v1/webhooks \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhook",
    "events": ["machine.offline", "command.failed", "schedule.failed"],
    "secret": "your-secret-key"
  }'

Response


{
  "data": {
    "id": "hook_abc123",
    "url": "https://example.com/webhook",
    "events": ["machine.offline", "command.failed", "schedule.failed"],
    "enabled": true,
    "created_at": "2024-01-20T15:45:00Z"
  }
}

How do I update a webhook?


PATCH /webhooks/:id

Request Body


{
  "events": ["machine.offline"],
  "enabled": false
}

How do I delete a webhook?


DELETE /webhooks/:id

What event types are available?

Session Events

Event	Description
`session.created`	New session created
`session.connected`	Agent connected to session
`session.client_attached`	Client attached to session
`session.client_detached`	Client detached from session
`session.grace_period`	Session entered grace period
`session.disconnected`	Session ended

Machine Events

Event	Description
`machine.online`	Machine came online
`machine.offline`	Machine went offline
`machine.registered`	New machine registered

Command Events

Event	Description
`command.started`	Command started executing
`command.completed`	Command finished successfully
`command.failed`	Command failed (non-zero exit)
`command.timeout`	Command timed out

File Events

Event	Description
`file.uploaded`	File uploaded
`file.downloaded`	File downloaded
`file.deleted`	File deleted

What does the webhook payload look like?

Webhooks are sent as POST requests with JSON body:


{
  "id": "evt_xyz789",
  "type": "machine.offline",
  "timestamp": "2024-01-20T15:45:00Z",
  "data": {
    "machine_id": "mach_abc123",
    "machine_name": "production-server",
    "last_seen": "2024-01-20T15:44:00Z"
  }
}

How do I verify webhook signatures?

If you provided a secret, verify the signature:


X-Cmdop-Signature: sha256=abc123...

Node.js Example


const crypto = require('crypto');
 
function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return `sha256=${expected}` === signature;
}
 
// In your handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-cmdop-signature'];
  const valid = verifySignature(req.rawBody, signature, process.env.WEBHOOK_SECRET);
 
  if (!valid) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process webhook
  const event = req.body;
  console.log(`Received ${event.type}`);
 
  res.status(200).send('OK');
});

What is the retry policy?

Failed deliveries are retried:

3 attempts
Exponential backoff: 1min, 5min, 30min
After all retries, webhook is disabled

How do I test a webhook?


POST /webhooks/:id/test

Sends a test event to your endpoint:


{
  "id": "evt_test",
  "type": "test",
  "timestamp": "2024-01-20T15:45:00Z",
  "data": {
    "message": "This is a test webhook"
  }
}