Skip to main content
A webhook sends task events to your system as HTTPS 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.
  1. Go to Settings → Webhooks in the dashboard.
  2. Paste your endpoint address under Endpoint address.
  3. Under Events, check each event you want to receive. task.created is checked for a new webhook. Check at least one event.
  4. Save.
  5. Copy the Secret. Your endpoint uses it to verify that requests come from Answering Agent.
  6. Click Send test. The page shows whether the test was delivered, and the error when it was not.
Answering Agent sends only the events you check. A webhook saved before the Events list existed has only 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 .local or .internal names are rejected.
  • Leave out a username and password.
To turn the webhook off, clear the address and save. Events that happen while the webhook is off are not sent later.

Verify requests

Every request carries these headers: To verify a request:
  1. 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.
  2. Split the Answering-Agent-Signature header on commas. Each part is key=value. Keep t and every v1 value.
  3. 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.
  4. Compare your result with each v1 value in constant time. Accept the request if any one matches. Today the header has one v1 value, but it can carry more than one in the future.
  5. Reject the request if t is more than 5 minutes before or after your server’s clock. This stops someone from sending an old request again.
Each retry has a new t and a new signature. The Answering-Agent-Event-Id stays the same.
The Node.js example uses only built-in modules. Save it as 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.
Clearing the address turns the webhook off. Events that happen while it is off are never sent, and retries still pending for earlier events stop. Answering Agent does not queue them for later.After you save the address again, fetch the tasks that changed while it was off with GET /tasks?updated_since=<the time you cleared it>. Skip any task your system already has, and compare each task’s status and assignee with your copy.

Event rules

These rules apply to every event:
  • id identifies one occurrence. Every retry of that occurrence has the same id, and the Answering-Agent-Event-Id header carries the same value. Skip any id you already processed.
  • Events can arrive out of order. For example, two task.updated events for one task can arrive in either order. For each task, store the occurred_at of 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 with GET /tasks/{task_id} instead.
  • task.updated and task.note_added are sent only for a task that GET /tasks/{task_id} returns, so their data is never null.
  • In task.updated and task.note_added, Answering Agent reads data once, when it first sends the event. Every retry sends the same body. data can already show a later change than the one the event reports.

The task.created event

Read the task from data. location, task, and caller are legacy fields kept for integrations built before data existed.
string
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.
string
task.created, or webhook.test for the test button.
string
When the conversation or form submission came in, as an ISO 8601 UTC timestamp.
integer
Your team ID.
object | null
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.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.
object
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.
object
object
The customer’s name and phone. Either can be null.

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.
string
A stable ID for this change, such as conversation:184532:task.updated:99120. Every retry of the same change has the same id.
string
When the change was saved, as an ISO 8601 UTC timestamp. Use it to put events for one task in order.
object
The task, the same object GET /tasks/{task_id} returns, as Answering Agent read it when it first sent the event.
object
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.
string
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.
string
When the note was added, as an ISO 8601 UTC timestamp.
object
The task, the same object GET /tasks/{task_id} returns, as Answering Agent read it when it first sent the event.
object
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.
Return a 2xx status so the test counts as delivered.

Delivery and retries

These rules apply to every event.
  • 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 with updated_since to find new tasks and status and assignee changes your endpoint missed. The API does not return notes, so a dropped task.note_added cannot be recovered.
  • 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.
Tasks that are not new do not send task.created. Examples are a repeat call that Answering Agent links to an existing task, or a conversation merged into another one.

No conversation events

Answering Agent sends task events only. It does not send an event when a conversation ends or a transcript is ready. To read conversations, transcripts, and report numbers, call the Customer API.