# Add a webhook

`POST https://api.chat-data.com/api/v2/add-webhook`

Canonical: https://www.chat-data.com/api-reference/add-webhook

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

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](/api-reference/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](/api-reference/get-conversations).

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| chatbotId | string | yes | The ID of the chatbot the webhook belongs to. |
| url | string | yes | The URL endpoint that the chatbot delivers events to. |
| event | string | yes | The type of event the webhook subscribes to. See [Webhooks](/api-reference/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. |
| contentType | string | no | The `Content-Type` of the deliveries. Endpoints on `hook.make.com`, `hook.*.make.com`, `n8n.cloud` and `*.n8n.cloud` always receive `text/plain`. Re-adding an existing `url` updates its content type. One of: `text/plain`, `application/json`. |

## Example request

```bash
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"
}'
```

## Example response (200)

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

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | The webhook could not be added. For example: the plan does not include webhooks, `event` is not a supported event, `url` is not a valid http(s) URL or points to a placeholder or Chat Data host, `contentType` is not supported, `chatbotId` is missing, or the chatbot already has 5 webhook endpoints. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |