Advanced Features
Webhooks Setup
Webhooks send events from your chatbot to your own server as they happen, such as each chat message, a new lead, or a WhatsApp template being delivered. Use them to sync Chat Data with your CRM, database or automation tools.
Webhook Setup
The supported events are chat, live-chat-escalation, lead-submission, user-online, user-offline, whatsapp-message-status and whatsapp-flow-response. Webhooks are set up per chatbot and are available on plans that include them (see pricing). A working receiver is in our example repository.
Step 1: Add an endpoint
- In your chatbot, open Settings > Webhooks and click Add an endpoint.
- Enter your endpoint URL (http or https).
- Under Events to send, select the events you want.
- Turn on JSON content type if your server expects
Content-Type: application/json. For Make and n8n Cloud webhook URLs, Chat Data always sendstext/plain, so the toggle is off for them. - Copy the Signing secret shown in the dialog and store it on your server. Each endpoint has its own secret; you can see it again by opening the endpoint. Refresh creates a new one; click Update to save it. Until then, events are still signed with the old secret.
- Click Create to save the endpoint.

Step 2: Receive and verify events
Each event is sent as a POST request to your endpoint:
- Body: the event payload as JSON text (see Events Payload). The
eventfield names the event. Content-Type:application/jsonif you turned on JSON content type; otherwise the body is sent astext/plain.x-chat-data-topicheader: the event name, for examplechat.x-chat-data-hmac-sha256header: a base64 HMAC-SHA256 of the raw body, signed with the endpoint's signing secret.
Verify the signature against the raw body, before parsing the JSON, to confirm the request came from Chat Data. This function is from the example repository:
const crypto = require('crypto');
// body: the raw request body (string or Buffer)
// signature: the x-chat-data-hmac-sha256 header
// signingSecret: the endpoint's signing secret
const verifySignature = (body, signature, signingSecret) => {
const digest = crypto
.createHmac('sha256', signingSecret)
.update(body)
.digest('base64');
const computedHmac = Buffer.from(digest, 'base64');
try {
return crypto.timingSafeEqual(computedHmac, Buffer.from(signature, 'base64'));
} catch (err) {
console.error(err.message);
return false;
}
};
With Express, read the raw body before anything parses it. Register this route before any app-wide app.use(express.json()); otherwise, with JSON content type on, the body is already parsed and every signature check fails:
app.post('/chat-data-webhook', express.raw({ type: '*/*', limit: '5mb' }), (req, res) => {
const signature = req.get('x-chat-data-hmac-sha256');
if (!verifySignature(req.body, signature, process.env.CHAT_DATA_SIGNING_SECRET)) {
return res.sendStatus(401);
}
res.sendStatus(200); // respond first, then process
const event = JSON.parse(req.body.toString('utf8'));
// handle event.event ...
});
Delivery and retries
Respond with a 2xx status as soon as you receive an event, and do slow work afterwards. There's no button to send a test event; check your endpoint with a real chat (for example, from your chatbot's Playground) and look for the delivery under Dashboard > Webhook Events.
| Your endpoint's response | What Chat Data does |
|---|---|
2xx | Delivered. |
404 or 5xx | Not retried (Chat Data treats these as the endpoint being down or misconfigured). Counts as a failed delivery. |
410 Gone | Not retried. The endpoint is disabled at once. |
Anything else (other 4xx such as 429, timeout, connection error) | Tried once more after 5 seconds. If that fails too, it counts as a failed delivery. |
After 20 failed deliveries in a row, the endpoint is disabled. When an endpoint is disabled, the workspace owners get an email. Fix your endpoint, then switch it back on in the Active column of Settings > Webhooks.
Because of the retry, an event can arrive twice, so make your processing safe to repeat. For whatsapp-message-status, message_id plus status identifies an event; for whatsapp-flow-response, message_id; for lead-submission, lead.uuid. The chat, live-chat-escalation, user-online and user-offline events carry no unique ID or timestamp, so use conversation_id together with the last message for those; two identical messages in a row will look like a duplicate.
Missed an event? Open Dashboard > Webhook Events in your chatbot to see recent deliveries with their result; live-chat-escalation and lead-submission deliveries can be resent while their conversation or lead still exists; other events can't be resent. For WhatsApp templates, you can also look up a message's current status with the Get a WhatsApp template message's status endpoint in the Chat Data API.
Events Payload
Chat
All conversations conducted with the corresponding chatbot will be delivered to your endpoints in near real-time after subscribing to the chat event type.
Here is an illustration of the fields that will be included in the event payload.
- messages: The conversation history up to the customer's latest message. Each message has a
role:useris the customer,assistantis the AI (or a template you sent), andhumanis a person on your team. The AI's reply to the latest message is inanswer. - hasFiles: Whether the last message contains files or images.
- answer: Response generated by the chatbot.
- client_ip: User's IP address if accessible (not available for chats from third-party integrations)
- chatbot_id: ID of the associated chatbot
- source: Where the conversation happens, for example
widget,iframeorapi. WhatsApp conversations useWhatsapp(exactly this spelling). - conversation_id: ID of an existing conversation thread
- cost_credits: Number of message credits consumed by this chat
- lead: The submitted lead in the conversation.
- event:
chat. - is_live_chat:
truefor messages exchanged in live chat, when a person is handling the conversation instead of the AI. Look at the last entry inmessages:role: "user"means a customer message arrived while the AI was paused,role: "human"means your team replied. These events have noanswerorcost_credits. On WhatsApp and other messaging channels, customer messages while the AI is paused are sent only when live chat is turned on in Settings > Live Chat.
Here is an example of the payload:
{
"messages": [
{
"role": "assistant",
"content": "👋 Hello there! I'm Chat Data AI, your go-to source for all things about Chat Data!"
},
{
"role": "assistant",
"content": "By the way, you can create a chatbot like me for your website! 😮"
},
{
"role": "user",
"content": "How to integrate with Discord?"
}
],
"hasFiles": false,
"answer": {
"role": "assistant",
"content": "You can follow the [guide](https://www.chat-data.com/api-reference#section/Chat-Data-Website-Guide/Discord-Bot-Integration) to integrate your chatbot with Discord.",
"score": 0.8503905227042547
},
"client_ip": "xx.xx.xx.xx",
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"source": "widget",
"cost_credits": 20,
"conversation_id": "dbf24043-83a6-47fb-b241-9865de3877c9",
"lead": {
"uuid": "28239132-671d-4b1f-9d43-1c7b70985ede"
},
"event": "chat"
}
Live Chat Escalation
When a conversation is escalated to live chat (the visitor clicks the live chat button, the AI or a workflow hands off, or a customer replies to a WhatsApp campaign set to Live chat replies), a live-chat-escalation event will be delivered to your webhook endpoints.
Here is an illustration of the fields that will be included in the event payload.
- messages: The conversation history so far, with the same
rolevalues as inchatevents. - notification_email: The list of email addresses that should be notified.
- chatbot_id: ID of the associated chatbot
- chatbot_name: The name of the associated chatbot.
- chatbot_display_name: The display name of the chatbot in the widget.
- handling_url: The URL that the agent can click to handle the live chat escalation request.
- conversation_id: ID of the conversation.
- conversation_start_time: When the conversation started (for AI and workflow escalations, when the escalation happened), as an ISO 8601 timestamp.
- lead: The submitted lead in the conversation.
- event:
live-chat-escalation.
Here is an example of the payload:
{
"messages": [
{
"role": "assistant",
"content": "👋 Hello there! I'm Chat Data AI, your go-to source for all things about Chat Data!"
},
{
"role": "assistant",
"content": "By the way, you can create a chatbot like me for your website! 😮"
},
{
"role": "user",
"content": "How to integrate with Discord?"
}
],
"notification_email": [
"[email protected]"
],
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"chatbot_name": "AI Chatbot",
"chatbot_display_name": "Chatbot Display Name",
"handling_url": "https://...",
"conversation_id": "dbf24043-83a6-47fb-b241-9865de3877c9",
"conversation_start_time": "2026-11-07T18:05:33.918Z",
"lead": {
"uuid": "28239132-671d-4b1f-9d43-1c7b70985ede"
},
"event": "live-chat-escalation"
}
Lead Submission
When a lead is submitted to your chatbot (through the lead form, collected by the AI, or by a workflow), a lead-submission event will be delivered to your webhook endpoints. It is sent only when the lead is first created; details added to an existing lead later don't send it. Leads created automatically from WhatsApp numbers and leads imported from a file don't send this event.
Here is an illustration of the fields that will be included in the event payload.
- chatbot_id: ID of the associated chatbot
- chatbot_name: The name of the associated chatbot.
- chatbot_display_name: The display name of the chatbot in the widget.
- lead: The submitted lead in the conversation.
- event:
lead-submission.
Here is an example of the payload:
{
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"chatbot_name": "AI Chatbot",
"chatbot_display_name": "Chatbot Display Name",
"lead": {
"uuid": "28239132-671d-4b1f-9d43-1c7b70985ede",
"name": "Name",
"phone": "+1 234 5678",
"email": "[email protected]"
},
"event": "lead-submission"
}
User Online
When a visitor in a live chat conversation comes online, a user-online event will be delivered to your webhook endpoints.
Here is an illustration of the fields that will be included in the event payload.
- chatbot_id: ID of the associated chatbot
- chatbot_name: The name of the associated chatbot.
- conversation_id: The ID of the conversation.
- source: The source of the conversation.
- name: The name of the user.
- email: The email of the user.
- phone: The phone number of the user.
- user_uuid: The UUID of the user.
- event:
user-online.
Here is an example of the payload:
{
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"chatbot_name": "AI Chatbot",
"conversation_id": "dbf24043-83a6-47fb-b241-9865de3877c9",
"source": "widget",
"name": "John Doe",
"email": "[email protected]",
"phone": "+1 234 5678",
"user_uuid": "28239132-671d-4b1f-9d43-1c7b70985ede",
"event": "user-online"
}
User Offline
When a visitor in a live chat conversation goes offline, a user-offline event will be delivered to your webhook endpoints.
Here is an illustration of the fields that will be included in the event payload.
- chatbot_id: ID of the associated chatbot
- chatbot_name: The name of the associated chatbot.
- conversation_id: The ID of the conversation.
- source: The source of the conversation.
- name: The name of the user.
- email: The email of the user.
- phone: The phone number of the user.
- user_uuid: The UUID of the user.
- event:
user-offline.
Here is an example of the payload:
{
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"chatbot_name": "AI Chatbot",
"conversation_id": "dbf24043-83a6-47fb-b241-9865de3877c9",
"source": "widget",
"name": "John Doe",
"email": "[email protected]",
"phone": "+1 234 5678",
"user_uuid": "28239132-671d-4b1f-9d43-1c7b70985ede",
"event": "user-offline"
}
WhatsApp Message Status
When a WhatsApp template message sent from Chat Data (from Outbound, Live Chat, a campaign or the API) changes status, a whatsapp-message-status event will be delivered to your webhook endpoints. Chat Data sends each status once, in order: sent, delivered, read, or failed if WhatsApp could not deliver it. failed can arrive with or without an earlier sent, but never after delivered or read. A message WhatsApp refuses at send time, or a campaign recipient Chat Data skips, gets no status event: API sends return the error, and campaigns show it on the campaign's detail page. A step can be skipped: if WhatsApp reports read before delivered, you get read and no delivered event. A retry can still make events reach you out of order, so keep the furthest status you've seen (sent < delivered < read). Replies are not sent as status events; the customer's reply arrives as a normal chat event, with source set to Whatsapp and the customer in lead (including lead.phone when known). For WhatsApp, conversation_id is your WhatsApp number and the customer's number, digits only, joined by a colon. To link a reply to a template you sent, match the customer's number against the recipient in the status events (compare digits only). If your chatbot has several WhatsApp numbers, also match the sending number: the reply's conversation_id starts with it, and you know it from your side (the number you sent from through the API, or the campaign's sending number). A customer has one conversation per number, so if you sent them several templates, the reply belongs to the conversation, usually answering the most recent one. Which WhatsApp messages produce a chat event:
| Message | chat event? |
|---|---|
| Customer message answered by the AI | Yes, with the AI's answer |
| Customer message while the AI is paused (Auto Off, the robot switch, or a campaign set to Live chat replies) | Yes, with is_live_chat: true, if live chat is turned on |
| Reply your team sends from Chat Data Live Chat | Yes, with is_live_chat: true |
| Reply you send from the WhatsApp Business app | No |
| Template you send | No; you get whatsapp-message-status events instead |
A customer's reply to a campaign, answered by the AI, looks like this:
{
"messages": [
{
"role": "assistant",
"content": "Hi Aisha, our spring sale starts today: 20% off all bouquets. Reply STOP to opt out."
},
{
"role": "user",
"content": "Do you deliver on Sundays?"
}
],
"hasFiles": false,
"answer": {
"role": "assistant",
"content": "Yes! We deliver on Sundays between 10 AM and 4 PM."
},
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"source": "Whatsapp",
"conversation_id": "14155550101:16045550133",
"cost_credits": 1,
"lead": {
"uuid": "16045550133",
"name": "Aisha Khan",
"phone": "16045550133"
},
"event": "chat"
}
Here is an illustration of the fields that will be included in the event payload.
- chatbot_id: ID of the associated chatbot.
- message_id: The WhatsApp message ID. It is in every status event, campaign messages included. For messages you sent with the Send a WhatsApp template message endpoint of the Chat Data API, it matches the
messageIdit returned. Campaign sends don't return message IDs to you, so match campaign events bycampaign_idandrecipient. - recipient: The customer's phone number in international format, without the
+. - campaign_id: The ID of the campaign the message belongs to. Only present for campaign messages.
- status:
sent,delivered,readorfailed. - timestamp: When WhatsApp reported the status, in ISO 8601 format.
- error_code and error_title: WhatsApp's error code and reason. Only present when the status is
failed. - billable and pricing_category: Whether WhatsApp charges for the message and its pricing category (for example
marketingorutility). Only present when WhatsApp includes pricing in the update.
Here is an example of the payload:
{
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"message_id": "wamid.HBgLMTQxNTU1NTI2NzEVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
"recipient": "16045550133",
"campaign_id": "6720c1f2a9e4b83d2c7a1f05",
"status": "delivered",
"timestamp": "2026-11-03T18:24:05.000Z",
"billable": true,
"pricing_category": "marketing",
"event": "whatsapp-message-status"
}
WhatsApp Flow Response
When a customer submits a WhatsApp Flow (form) from a template message sent from Chat Data, a whatsapp-flow-response event will be delivered to your webhook endpoints.
Here is an illustration of the fields that will be included in the event payload.
- chatbot_id: ID of the associated chatbot.
- message_id: The WhatsApp message ID of the template that contained the Flow.
- recipient: The customer's phone number in international format, without the
+. - campaign_id: The ID of the campaign the message belongs to. Only present for campaign messages.
- response: The answers the customer submitted, keyed by the field names of your Flow, as sent by WhatsApp. It also includes
flow_token, which Chat Data uses internally; you can ignore it. - event:
whatsapp-flow-response.
Here is an example of the payload:
{
"chatbot_id": "654aee418bc9a33b0e50d0ad",
"message_id": "wamid.HBgLMTQxNTU1NTI2NzEVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
"recipient": "16045550133",
"response": {
"flow_token": "6720c3a8a9e4b83d2c7a1f9b",
"preferred_date": "2026-11-10",
"party_size": "4"
},
"event": "whatsapp-flow-response"
}
For WhatsApp templates and campaigns, see WhatsApp Integration.
Frequently Asked Questions
Where do I find the webhook signing secret?
In your chatbot, open Settings > Webhooks > Add an endpoint. Each endpoint has its own signing secret, shown in that dialog. Webhooks are available on plans that include them; see the pricing page.
How do I verify that a webhook request really came from Chat Data?
Compute an HMAC-SHA256 of the raw request body with the endpoint's signing secret, base64-encode it, and compare it with the x-chat-data-hmac-sha256 header. Verify before parsing the JSON.
Which webhook events are supported?
Seven events are supported: chat, live-chat-escalation, lead-submission, user-online, user-offline, whatsapp-message-status and whatsapp-flow-response. The last two cover WhatsApp template messages sent from Chat Data.
What information is included in the chat webhook payload?
The chat history (messages), whether the last message has files (hasFiles), the chatbot answer, the client IP when available, the chatbot ID, source, conversation ID, credits used (cost_credits), the lead, the event name, and is_live_chat for messages handled by a person.