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.

KindWhat it receives
DiscordA formatted card posted through a Discord webhook URL
SlackA formatted message posted through a Slack incoming webhook URL
TelegramA formatted message sent by your bot to a chat
Custom HTTPA 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

EventSent when
conversation.createdA 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.receivedA visitor sends a message
conversation.escalatedAiva hands the conversation to your team, or cannot answer (ai_unavailable)
conversation.assignedA teammate becomes responsible for the conversation
conversation.unassignedThe conversation no longer has a responsible teammate
handoff.overdueNobody 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.transferredA teammate transferred the conversation to another team, or deleted the team that held a handoff waiting in it
conversation.resolvedThe conversation is resolved
conversation.closedThe 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:

FieldEventsMeaning
conversationIdallThe conversation's id
contactNameallThe visitor's name, or a fallback when they have not given one
messagePreviewmessage.receivedThe first 300 characters of the message
reasonconversation.escalatedWhy Aiva handed the conversation over
summaryconversation.escalatedAiva's summary for the team
isUrgentconversation.escalatedWhether the request was marked urgent
agentNameconversation.assignedThe teammate now responsible
assignerNameconversation.assigned, conversation.unassigned, conversation.transferredThe teammate who made the change, absent when the product made it
teamall, once a team holds the conversationThe team that holds the conversation: id and name
assigneeall, while a teammate is responsibleThe teammate responsible for the conversation: id and name
handoffconversation.escalated, handoff.overdue, conversation.transferredThe handoff: its id, and dueAt, when the team's response target passes. For a transfer, the receiving team's handoff
reassignedhandoff.overdueWhether 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
fromTeamconversation.transferredThe team the conversation left: id and name. Absent when it had none
toTeamconversation.transferredThe team the conversation reached: id and name. team names it too
noteconversation.transferredThe 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

HeaderValue
X-Assistify-EventThe event name, the same as event in the body
X-Assistify-TimestampUnix seconds at signing
X-Assistify-Signaturesha256= followed by the hex HMAC-SHA256 of <timestamp>.<raw body>
X-Assistify-Delivery-IdA 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." } }