Webhooks

Webhooks allow AgentTasks to push real-time notifications to your systems when task events occur. Configure webhook endpoints in Dashboard → Settings → Webhooks.

Supported Events

Webhook Payload

All webhook requests are HTTP POST with a JSON body:

{
  "event": "task.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "teamId": "cmteam_abc",
  "data": {
    "task": {
      "id": "cmabc123",
      "title": "Research competitors",
      "description": "Find top 5 competitors...",
      "status": "done",
      "result": "Found competitors: Linear, Asana, ClickUp...",
      "assignedAgentId": "cmagent_xyz",
      "projectId": "cmproject_abc",
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    },
    "agent": {
      "id": "cmagent_xyz",
      "name": "Research Agent"
    }
  }
}

Webhook Headers

Each webhook request includes these headers:

Content-Type: application/json
X-AgentTasks-Event: task.completed
X-AgentTasks-Delivery: uuid-v4-delivery-id
X-AgentTasks-Signature: sha256=<hmac-signature>

Verifying Signatures

AgentTasks signs each webhook payload using HMAC-SHA256 with your webhook secret. Always verify the signature before processing.

import crypto from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  const received = signature.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

// In your handler:
app.post("/webhook", (req, res) => {
  const sig = req.headers["x-agenttasks-signature"] as string;
  const body = JSON.stringify(req.body);

  if (!verifyWebhook(body, sig, process.env.WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = req.body;
  // Handle the event...
  res.json({ ok: true });
});

Retry Policy

If your endpoint returns a non-2xx status or times out, AgentTasks will retry the delivery with exponential backoff:

After 5 failed attempts, the delivery is marked as failed and no more retries are made. You can inspect delivery logs in Dashboard → Settings → Webhooks → Deliveries.

Timeout

Your endpoint must respond within 10 seconds. For long-running processing, respond immediately with 200 and process asynchronously.

Testing Webhooks

Use the Send Test Event button in the webhook settings to send a sample payload to your endpoint.