Workspace webhooks reference
Events, payloads, headers and signature verification for workspace webhooks.
A workspace webhook tells one of your own endpoints when something happens to a conversation. You add destinations in the dashboard under Settings → Alerts. Each destination is one of four kinds and subscribes to the events you choose.
| Kind | What it receives |
|---|---|
| Discord | A formatted card posted through a Discord webhook URL |
| Slack | A formatted message posted through a Slack incoming webhook URL |
| Telegram | A formatted message sent by your bot to a chat |
| Custom HTTP | A signed JSON body sent to your endpoint. Use an HTTPS URL. |
The rest of this page describes the Custom HTTP kind, which is the one meant for code.
Events
| Event | Sent when |
|---|---|
conversation.created | A visitor starts a conversation (in Webchat, from a campaign card, in a Discord ticket or a Telegram chat), or replies to a conversation a teammate started. Not sent for API conversations |
message.received | A visitor sends a message |
conversation.escalated | Aiva hands the conversation to your team, or cannot answer (ai_unavailable) |
conversation.assigned | A teammate becomes responsible for the conversation |
conversation.unassigned | The conversation no longer has a responsible teammate |
handoff.overdue | Nobody replied to a handoff within the response target you set for the team: taking it without replying does not count. Never sent for a team without one |
conversation.transferred | A teammate transferred the conversation to another team, or deleted the team that held a handoff waiting in it |
conversation.resolved | The conversation is resolved |
conversation.closed | The conversation is closed |
conversation.escalated is not sent when a campaign's conversation step hands the conversation to a team, or in a workspace where Aiva does not answer; handoff.overdue can still follow those handoffs. The dashboard offers conversation.transferred once your workspace has more than one team, ticked by default on a new destination; a destination added earlier receives it once you tick it.
When a team assigns automatically, a conversation handed to it goes to an available member connected to the workspace (from the dashboard or the mobile app) with the fewest open conversations, and that assignment is a conversation.assigned with no assignerName. So is a move to another member when the first one leaves before replying, or when nobody picks it up within the team's response target. When the conversation goes back to the whole team instead, it is a conversation.unassigned with no assignerName.
Body
Every delivery has the same envelope:
{
"event": "conversation.assigned",
"timestamp": "2026-09-28T14:02:11.000Z",
"data": {
"conversationId": "c2779aa20b318-476a1184e6fc2",
"contactName": "Ada",
"agentName": "Grace",
"assignerName": "Alan",
"team": { "id": "cm1team8x0001", "name": "Support" },
"assignee": { "id": "cm1mbr4k20007", "name": "Grace" }
},
"links": {
"conversation": "https://dash.assistify.chat/open/…"
}
}Fields in data, by event:
| Field | Events | Meaning |
|---|---|---|
conversationId | all | The conversation's id |
contactName | all | The visitor's name, or a fallback when they have not given one |
messagePreview | message.received | The first 300 characters of the message |
reason | conversation.escalated | Why Aiva handed the conversation over |
summary | conversation.escalated | Aiva's summary for the team |
isUrgent | conversation.escalated | Whether the request was marked urgent |
agentName | conversation.assigned | The teammate now responsible |
assignerName | conversation.assigned, conversation.unassigned, conversation.transferred | The teammate who made the change, absent when the product made it |
team | all, once a team holds the conversation | The team that holds the conversation: id and name |
assignee | all, while a teammate is responsible | The teammate responsible for the conversation: id and name |
handoff | conversation.escalated, handoff.overdue, conversation.transferred | The handoff: its id, and dueAt, when the team's response target passes. For a transfer, the receiving team's handoff |
reassigned | handoff.overdue | Whether the handoff went to another teammate, who then holds it. When false it stays where it was, and the team's lead is told the first time it is overdue, unless the lead holds it |
fromTeam | conversation.transferred | The team the conversation left: id and name. Absent when it had none |
toTeam | conversation.transferred | The team the conversation reached: id and name. team names it too |
note | conversation.transferred | The note the teammate left for the receiving team, when there is one |
team and assignee describe the conversation when the event is sent. An assignee id identifies a member of your workspace; the same person has a different id in another workspace.
reason is one of user_requested, cannot_answer, frustrated_user, requires_authorization, unresolved_attempts, sensitive_topic or ai_unavailable.
Fields are only ever added. Ignore fields you do not recognize. The body is built for each attempt, so its timestamp is the time of that attempt.
Headers
| Header | Value |
|---|---|
X-Assistify-Event | The event name, the same as event in the body |
X-Assistify-Timestamp | Unix seconds at signing |
X-Assistify-Signature | sha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw body> |
X-Assistify-Delivery-Id | A UUID that stays the same across retries of one delivery |
Verifying the signature
Compute the HMAC over the timestamp, a dot and the raw request body, with the destination's signing secret, shown once when you add the destination. Compare it with the header in constant time, and reject a timestamp that is too old for your needs.
import { createHmac, timingSafeEqual } from 'node:crypto';
function isFromAssistify(rawBody, headers, secret) {
const timestamp = headers['x-assistify-timestamp'];
const expected = 'sha256=' + createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
const received = headers['x-assistify-signature'] ?? '';
return expected.length === received.length && timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}Retries
A delivery that does not get a 2xx response within 10 seconds is retried up to five attempts in all, with an exponential backoff starting at two seconds. Redirects are not followed and count as a failure. Every attempt carries the same X-Assistify-Delivery-Id, so you can ignore one you have already processed.
After 10 deliveries in a row fail all their attempts, the destination is turned off. Turning it back on in Settings → Alerts starts the count again.
Test delivery
The test button on a destination sends the event test.ping once, without retries, and shows the result on the page. The event name is in the header and in the body:
{ "event": "test.ping", "timestamp": "…", "data": { "message": "This endpoint receives Assistify events." } }