Skip to content

Add a webhook

post/add-webhook
Any key

Add a webhook endpoint that receives real-time events from the chatbot: chat, live-chat-escalation, lead-submission, user-online or user-offline. Your plan must include webhooks. A chatbot can have up to 5 webhook endpoints; adding an event to an existing url subscribes that endpoint to one more event.

The Webhooks page documents every event's body and how to verify deliveries. A chat event triggered by a /chat request with skipCache: true carries regenerate: true (the field is absent otherwise). A live-chat-escalation matches its chat event by conversation_id; a lead-submission has no conversation_id, so pass its lead.uuid as leadId to Get conversations.

Request body

Sending 3 of 4 fields
Required
chatbotIdstring
The ID of the chatbot the webhook belongs to.
urlstring
The URL endpoint that the chatbot delivers events to.
eventstring
The type of event the webhook subscribes to. See Webhooks for the chat, live-chat-escalation and lead-submission bodies. user-online and user-offline fire when the user joins or leaves a live chat session and carry chatbot_id, chatbot_name, conversation_id and, when known, the user's name, email, phone, source and user_uuid. If a webhook with this url already exists, the event is added to its subscriptions.

Only these fields are sent (application/json).

Try it · POST /add-webhook
curl 'https://api.chat-data.com/api/v2/add-webhook' \  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \  -H 'Content-Type: application/json' \  -d '{  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",  "url": "https://example.com/webhooks/chat-data",  "event": "chat"}'
Loading…

Responses

Successful response.

Content type: application/json

FieldDescription
statusstringOne of: success.
webhooksarray of objectThe chatbot's webhooks after the change.
webhooks[].endpointstringThe URL endpoint that the chatbot delivers events to.
webhooks[].eventsarray of stringAn array of events that the webhook subscribes to. See Webhooks for the event bodies.
webhooks[].secretstringThe secret used to sign deliveries. The x-chat-data-hmac-sha256 header carries the Base64 HMAC-SHA256 of the raw request body, keyed with this secret.
webhooks[].enablebooleanIndicates whether the webhook is turned on.
webhooks[].contentTypestringThe Content-Type of the deliveries. One of: text/plain, application/json.

Example

{  "status": "success",  "webhooks": [    {      "endpoint": "https://example.com/webhooks/chat-data",      "events": [        "chat"      ],      "secret": "4f9a2c7e1b8d3f6a0c5e9b2d7a1f4c8e3b6d9f2a5c8e1b4d7f0a3c6e9b2d5f8a",      "enable": true,      "contentType": "text/plain"    }  ]}

Last updated October 14, 2026