Webhooks

Webhooks push Chat Data events to your own HTTP or HTTPS endpoint (HTTPS recommended) as they happen, so you don't have to poll.

Register an endpoint with Add a webhook and remove it with Delete a webhook, or manage webhooks in the chatbot's settings (guide). The response lists each webhook with its secret; keep it on your server.

What a delivery looks like

Each event is a POST to your URL with a JSON body and these headers:

Verify that a delivery came from Chat Data

Compute the HMAC over the raw body (before JSON parsing) and compare it to the header in constant time.

Node.js

import crypto from 'node:crypto'; // Express: app.post('/chat-data-webhook', express.raw({ type: '*/*' }), handler)function isFromChatData(rawBody, signatureHeader, secret) {  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64');  const a = Buffer.from(expected);  const b = Buffer.from(signatureHeader || '');  return a.length === b.length && crypto.timingSafeEqual(a, b);}

Python

import base64, hashlib, hmac def is_from_chat_data(raw_body: bytes, signature_header: str, secret: str) -> bool:    expected = base64.b64encode(hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()).decode()    return hmac.compare_digest(expected, signature_header or "")

Respond, retries and disabling

• Reply with any 2xx status as soon as you have the event, and do slow work afterwards.
• A failed delivery (a network error, a timeout, or a 4xx other than 404/410) is retried once, 5 seconds later.
• 404 and 5xx responses are not retried.
• 410 Gone turns the webhook off immediately. After 20 failed deliveries in a row it is also turned off. Once your endpoint is healthy, re-enable the webhook on the chatbot's Settings → Webhooks page, or delete it and add it again (adding the same URL again does not turn it back on).

Event bodies

live-chat-escalation carries chatbot_id, chatbot_name, chatbot_display_name, notification_email, handling_url (where an agent takes over), conversation_id, conversation_start_time, messages, source and lead.

lead-submission carries chatbot_id, chatbot_name, chatbot_display_name and lead (the submitted name, email, phone, source, any custom form fields, and uuid). It has no conversation_id; pass lead.uuid as leadId to Get conversations to find the conversation.

user-online and user-offline carry chatbot_id, chatbot_name, conversation_id and, when known, the visitor's name, email, phone, source and user_uuid.