Webhooks

Get real-time HTTP notifications when events happen in your Delegated workspace.

Overview

Webhooks let you receive real-time notifications about events in your Delegated workspace. Instead of polling the API, Delegated sends an HTTP POST request to your endpoint whenever something happens.

Use webhooks to build custom integrations, trigger external workflows, or sync Delegated with your own systems.

Setting Up a Webhook

Configure webhooks in Settings → API → Webhooks, or via the API:

POST /api/webhooks/create
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://your-server.com/webhook/delegated",
  "events": ["task.created", "task.completed", "agent.alert"],
  "secret": "your-webhook-secret"
}

Parameters:

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to receive events
`events`	array	Yes	List of event types to subscribe to
`secret`	string	No	Shared secret for signature verification

Available Events

Event	Description
`task.created`	A new task was added to the board
`task.started`	Agent moved a task to DOING
`task.completed`	Agent moved a task to DONE
`task.failed`	A task failed or was blocked
`agent.alert`	Agent flagged something for attention
`email.received`	New email detected via IMAP
`order.new`	New Shopify order received

Payload Format

Every webhook delivery is an HTTP POST with a JSON body:

POST https://your-server.com/webhook/delegated
Content-Type: application/json
X-Delegated-Event: task.completed
X-Delegated-Signature: sha256=abc123...
X-Delegated-Delivery: evt_9xMkLp

{
  "event": "task.completed",
  "timestamp": "2026-03-04T12:45:00Z",
  "data": {
    "task_id": "task_8xK2mP",
    "title": "Generate weekly ad creatives",
    "status": "DONE",
    "started_at": "2026-03-04T12:30:00Z",
    "completed_at": "2026-03-04T12:45:00Z",
    "duration_seconds": 900,
    "result": "5 ad variations generated and saved"
  }
}

Signature Verification

If you provided a secret when creating the webhook, every delivery includes an X-Delegated-Signature header. Verify it to ensure the request came from Delegated:

// Node.js example
const crypto = require('crypto');

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

// In your webhook handler:
app.post('/webhook/delegated', (req, res) => {
  const sig = req.headers['x-delegated-signature'];
  if (!verifySignature(JSON.stringify(req.body), sig, 'your-secret')) {
    return res.status(401).send('Invalid signature');
  }
  // Process the event...
  res.status(200).send('OK');
});

Important: Always verify webhook signatures in production. Without verification, anyone could send fake events to your endpoint.

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), Delegated will retry the delivery:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry (final)	12 hours

After 5 failed attempts, the delivery is marked as failed. You can view failed deliveries in Settings → Webhooks → Delivery Log.

Tip: Return a 200 status quickly and process the event asynchronously. This prevents timeouts if your processing takes a while.

Testing Webhooks

Use the Test button in the webhook settings to send a sample event to your endpoint. You can also use tools like webhook.site for debugging.

Next Steps

Tasks API — Manage tasks programmatically
Notifications — Built-in notification channels
Integrations — Connect external services