POST requests. Use it to open a ticket in Zendesk, update a ClickUp card when the task changes, or page a manager, without polling the Customer API.
Answering Agent sends these events:
Set up the webhook
Team owners and admins manage the webhook. Each team has one webhook address.- Go to Settings → Webhooks in the dashboard.
- Paste your endpoint address under Endpoint address.
- Under Events, check each event you want to receive.
task.createdis checked for a new webhook. Check at least one event. - Save.
- Copy the Secret. Your endpoint uses it to verify that requests come from Answering Agent.
- Click Send test. The page shows whether the test was delivered, and the error when it was not.
task.created checked, and it gets nothing new until you check more events and save.
The address must:
- Start with
https://. - Use a public domain name. IP addresses,
localhost, and.localor.internalnames are rejected. - Leave out a username and password.
Verify requests
Every request carries these headers:
To verify a request:
- Read the raw request body as bytes. Verify before you parse the JSON, because a parsed and re-serialized body can differ from the bytes Answering Agent signed.
- Split the
Answering-Agent-Signatureheader on commas. Each part iskey=value. Keeptand everyv1value. - Compute an HMAC-SHA256 of
t, a period, and the raw body. Use the secret as the key, exactly as Settings → Webhooks shows it, as UTF-8 bytes. Write the result as lowercase hex. - Compare your result with each
v1value in constant time. Accept the request if any one matches. Today the header has onev1value, but it can carry more than one in the future. - Reject the request if
tis more than 5 minutes before or after your server’s clock. This stops someone from sending an old request again.
t and a new signature. The Answering-Agent-Event-Id stays the same.
server.mjs and run it with node server.mjs. If you use Express, read the body with express.raw({ type: 'application/json' }) instead of express.json(), then pass req.body to verifyAnsweringAgentSignature. In Flask, request.get_data() returns the raw body.
To test your code, check that it accepts this input when the current time is 1791297234. In the Node.js example, pass that time as the fourth argument to verifyAnsweringAgentSignature.
The
X-Answering-Agent-Secret header still arrives on every request, so receivers that compare it with the secret keep working. That header holds the secret itself, so anyone who sees one request can send requests your endpoint accepts. Verify the signature in new code. Store the secret like a password either way.
Change the secret
Saving a new address keeps the same secret. To get a new secret, clear the address and save, then enter the address again and save. The page then shows a new secret. Update your endpoint before you send the next test. Clearing the address also clears your Events choices. Check the events you want again before you save the address the second time.Event rules
These rules apply to every event:ididentifies one occurrence. Every retry of that occurrence has the sameid, and theAnswering-Agent-Event-Idheader carries the same value. Skip anyidyou already processed.- Events can arrive out of order. For example, two
task.updatedevents for one task can arrive in either order. For each task, store theoccurred_atof the newest event you received, including events you skip, such as the one your own update sends. Never apply an event older than that. Read the task again withGET /tasks/{task_id}instead. task.updatedandtask.note_addedare sent only for a task thatGET /tasks/{task_id}returns, so theirdatais nevernull.- In
task.updatedandtask.note_added, Answering Agent readsdataonce, when it first sends the event. Every retry sends the same body.datacan already show a later change than the one the event reports.
The task.created event
data. location, task, and caller are legacy fields kept for integrations built before data existed.
A stable ID for this event, in the form
{source_type}:{source_id}:task.created. Every retry of the same event has the same id. Use it to skip duplicates.The task, the same object
GET /tasks/{task_id} returns, with its id, status, assignee, category, priority, customer, source conversation or form, and description. It uses the API’s names and IDs. Answering Agent reads the task after any automatic assignment and again for each retry, so data shows the task as it is when that request is sent. null when the dashboard does not show the task.Legacy fields
location, task, and caller came before data. They keep their original names and values so existing integrations keep working. Read data in new code. The legacy values differ from data in these ways:
task.channeluses the stored channel namesphone_call,sms,chat_widget, andemail.data.conversation.channelusesphone,text,web_chat, andemail.task.categoryis a display label from a separate task category list, such asRetention.data.categoryis the conversation’s category key, such ascancellation.task.titleandtask.descriptioncome from the first follow-up the AI wrote.data.titleanddata.descriptionare what the dashboard shows for the task, and they can differ.task.source_typeandtask.source_ididentify the source.data.idis already the API task ID, such asconversation-184532.
The phone line the task came from:
phone_number_id, name, and phone_number. Each can be null, for example for a form submission that is not tied to a line.The task.updated event
Answering Agent sends task.updated when a task’s status or assignee changes. The change can come from the dashboard, a bulk edit, the Customer API, the MCP server, or the AI, for example when the AI marks a task done after a call. A change to anything else, such as the title or category, sends nothing.
A few automatic changes send no task.updated today: a transferred call that reopens a task, the AI clearing an assignee nobody claimed, and automatic assignment after the AI reviews a text conversation. To catch them, also poll for changes with updated_since.
Creating a task sends task.created, not task.updated. When automatic assignment runs on a new task, a task.updated with the new assignee can arrive just before or just after its task.created.
A stable ID for this change, such as
conversation:184532:task.updated:99120. Every retry of the same change has the same id.When the change was saved, as an ISO 8601 UTC timestamp. Use it to put events for one task in order.
The task, the same object
GET /tasks/{task_id} returns, as Answering Agent read it when it first sent the event.What changed. It has a
status key, an assignee key, or both. A key is present only when that value changed.The task.note_added event
Answering Agent sends task.note_added when someone adds an internal note to a conversation task. The note can come from the dashboard, POST /tasks/{task_id}/notes, or the MCP server. Form tasks do not take notes.
A stable ID for this note event, such as
conversation:184532:task.note_added:552204. Every retry of the same event has the same id.The task, the same object
GET /tasks/{task_id} returns, as Answering Agent read it when it first sent the event.The note, the same object
POST /tasks/{task_id}/notes returns.The webhook.test event
Send test posts a short event with the same headers. It has no location, task, caller, or data. The test goes out no matter which events you checked.
2xx status so the test counts as delivered.
Delivery and retries
These rules apply to every event.- Response. Return any
2xxstatus within 8 seconds. Do the slow work after you respond. - Retries. A
5xx,408, or429response, 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 aRetry-Afterheader. After the last failed retry, the event is dropped. UseGET /taskswithupdated_sinceto find new tasks and status and assignee changes your endpoint missed. The API does not return notes, so a droppedtask.note_addedcannot be recovered. - No retry. Other responses, including
3xxand4xx, 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
idyou already processed. - Status. Settings → Webhooks shows when the last delivery succeeded or failed, and the last error.
task.created. Examples are a repeat call that Answering Agent links to an existing task, or a conversation merged into another one.