Webhooks

​

Set up the webhook

1. Go to Settings → Webhooks in the dashboard.
2. Paste your endpoint address under Endpoint address and save.
3. Copy the Secret. Your endpoint uses it to check that requests come from Answering Agent.
4. Click Send test. The page shows whether the test was delivered, and the error when it was not.

• Start with https://.
• Use a public domain name. IP addresses, localhost, and .local or .internal names are rejected.
• Leave out a username and password.

​

Check the secret

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = Buffer.from(process.env.ANSWERING_AGENT_WEBHOOK_SECRET);

app.post('/answering-agent', express.json(), (req, res) => {
  const received = Buffer.from(req.get('X-Answering-Agent-Secret') ?? '');
  if (received.length !== secret.length || !crypto.timingSafeEqual(received, secret)) {
    return res.sendStatus(401);
  }

  const event = req.body;
  if (event.event === 'task.created' && event.data) {
    // Create the ticket from event.data. Skip event.id values you already processed.
  }
  res.sendStatus(200);
});

​

Change the secret

​

The task.created event

POST /answering-agent HTTP/1.1
Content-Type: application/json
X-Answering-Agent-Secret: 3q2-7wZk1yHf0aLr9TbXc4VdN8sMpQe2

{
  "id": "conversation:184532:task.created",
  "event": "task.created",
  "occurred_at": "2026-10-05T14:21:07.000Z",
  "team_id": 410,
  "location": {
    "phone_number_id": 2181,
    "name": "Westside Wash",
    "phone_number": "+15125550142"
  },
  "task": {
    "source_type": "conversation",
    "source_id": 184532,
    "channel": "phone_call",
    "title": "Cancel monthly membership",
    "description": "Dana Ruiz wants to cancel her Unlimited membership before the charge on the 12th. She is moving out of state and declined the free-month offer. Confirm the cancellation in the POS and reply by text.",
    "category": "Retention",
    "url": "https://answeringagent.com/dashboard/conversations/184532"
  },
  "caller": {
    "name": "Dana Ruiz",
    "phone": "+15125550118"
  },
  "data": {
    "id": "conversation-184532",
    "url": "https://answeringagent.com/dashboard/conversations/184532",
    "title": "Cancel monthly membership",
    "status": "open",
    "assignee": { "id": 9034, "name": "Priya Shah" },
    "category": "cancellation",
    "priority": "high",
    "created_at": "2026-10-05T14:21:07.000Z",
    "customer": { "name": "Dana Ruiz", "phone": "+15125550118", "email": "dana.ruiz@example.com" },
    "conversation": {
      "id": 184532,
      "url": "https://answeringagent.com/dashboard/conversations/184532",
      "channel": "phone",
      "phone_line": { "id": 2181, "name": "Westside Wash", "phone_number": "+15125550142" }
    },
    "form": null,
    "description": "Dana Ruiz wants to cancel her Unlimited membership before the charge on the 12th. She is moving out of state and declined the free-month offer. Confirm the cancellation in the POS and reply by text."
  }
}

​

Legacy fields

• task.channel uses the stored channel names phone_call, sms, chat_widget, and email. data.conversation.channel uses phone, text, web_chat, and email.
• task.category is a display label from a separate task category list, such as Retention. data.category is the conversation’s category key, such as cancellation.
• task.title and task.description come from the first follow-up the AI wrote. data.title and data.description are what the dashboard shows for the task, and they can differ.
• task.source_type and task.source_id identify the source. data.id is already the API task ID, such as conversation-184532.

​

The webhook.test event

{
  "id": "webhook:410:test:1791297234567",
  "event": "webhook.test",
  "occurred_at": "2026-10-06T14:33:54.567Z",
  "team_id": 410
}

​

Delivery and retries

• Response. Return any 2xx status within 8 seconds. Do the slow work after you respond.
• Retries. A 5xx, 408, or 429 response, a timeout, or a connection error counts as a failed attempt. Answering Agent retries a failed delivery up to 4 more times, waiting longer between attempts. It ignores a Retry-After header. After the last failed retry, the event is dropped. Use GET /tasks to find tasks your endpoint missed.
• No retry. Other responses, including 3xx and 4xx, end delivery for that event. Answering Agent does not follow redirects, so point the webhook at the final address.
• Duplicates. Your endpoint can get the same event more than once, for example when it saved the task but answered after the timeout. Skip any id you already processed.
• Status. Settings → Webhooks shows when the last delivery succeeded or failed, and the last error.

​

Other events