Webhook Events

Cortex delivers events to registered webhook URLs via HTTP POST. Use webhooks for event-driven automation, CI/CD integration, and alerting.

Registering a Webhook

curl -X POST https://api.cortex.acrobi.com/api/webhooks/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/cortex-webhook",
    "events": ["agent.completed", "agent.failed", "task.status_changed"],
    "secret": "your-webhook-secret"
  }'

Response:

{
  "id": "wh-abc123",
  "url": "https://your-server.com/cortex-webhook",
  "events": ["agent.completed", "agent.failed", "task.status_changed"],
  "createdAt": "2026-04-03T12:00:00.000Z"
}

Supported Events

Event	Trigger
task.created	New task created
task.completed	Task moved to done status
task.status_changed	Any task status transition
agent.spawned	Agent execution started
agent.completed	Agent execution finished successfully
agent.failed	Agent execution errored

Webhook Payload

All webhooks deliver a JSON payload with this structure:

{
  "event": "agent.completed",
  "data": {
    "agentId": "agent-123",
    "agentName": "my-coder-agent",
    "taskId": "task-456",
    "result": "Code review completed",
    "duration": 12500,
    "timestamp": "2026-04-03T12:05:00.000Z"
  },
  "timestamp": "2026-04-03T12:05:00.123Z"
}

Security Headers

Every webhook delivery includes these verification headers:

Header	Description
X-Cortex-Signature	HMAC-SHA256 signature of the payload body
X-Cortex-Event	Event type (e.g., agent.completed)
X-Cortex-Delivery	Unique delivery ID (UUID)
X-Cortex-Timestamp	ISO 8601 timestamp of the delivery

Verifying Webhook Signatures

Verify the X-Cortex-Signature header to ensure the payload is authentic:

Node.js

const crypto = require('crypto');

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

// In your handler:
app.post('/cortex-webhook', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-cortex-signature'];
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  const { event, data } = req.body;
  console.log(`Received ${event}:`, data);
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Testing Webhooks

Send a test payload to verify your endpoint:

curl -X POST https://api.cortex.acrobi.com/api/webhooks/wh-abc123/test \
  -H "Authorization: Bearer $TOKEN"

Delivery History

View delivery attempts and their status:

curl https://api.cortex.acrobi.com/api/webhooks/wh-abc123/deliveries \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "deliveries": [
    {
      "id": "del-001",
      "event": "agent.completed",
      "status": "delivered",
      "responseCode": 200,
      "duration": 150,
      "timestamp": "2026-04-03T12:05:00.000Z"
    },
    {
      "id": "del-002",
      "event": "agent.failed",
      "status": "failed",
      "responseCode": 500,
      "retries": 3,
      "timestamp": "2026-04-03T12:10:00.000Z"
    }
  ]
}

Extended Activity Events (WebSocket Only)

These additional events are available via WebSocket but not delivered to webhooks:

Event	Description
agent.status	Real-time status changes (error/blocked)
task.updated	Task detail modifications
task.deleted	Task removals
chief.plan.created	Chief coordinator created a plan
chief.task.assigned	Chief assigned task to agent
chief.task.progress	Task progress update
swarm.phase.started	Swarm entered new phase
swarm.phase.completed	Swarm phase finished
gate.passed	Quality gate passed
gate.failed	Quality gate failed
chat.message	New chat message