---
title: "Configure Omnichannel Event Webhooks"
slug: "webhooks"
updated: 2026-01-22T08:50:17Z
published: 2026-01-22T08:50:17Z
canonical: "docs.rocket.chat/webhooks"
excludeFromExternalSearch: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Omnichannel Event Webhooks

The Omnichannel Webhooks feature lets you integrate your Omnichannel events with third-party systems, such as a CRM (e.g., Zoho) or a custom application. When specific Omnichannel events occur, Rocket.Chat sends structured data (JSON payloads) in real-time to your configured webhooks. You can choose how the webhook should respond, for example, by sending automated messages in response to visitor messages in Livechat.

## Omnichannel Webhook events

Below is a list of the available Omnichannel events to send data to your configured webhook:

| Event | Description |
| --- | --- |
| **Chat Start** | Triggered when a visitor initiates a chat. |
| **Chat Close** | Triggered when a chat is ended by a visitor or an agent. |
| **Chat Taken** | Triggered when an agent accepts or takes a chat. |
| **Chat Queued** | Triggered when a chat is placed in a queue (e.g., when forwarded to a different department). |
| **Forwarding** | Triggered when a chat is transferred to a new agent or department. |
| **Offline Messages** | Triggered when a visitor leaves a message while agents are offline. |
| **Visitor Messages** | Triggered when a visitor sends a message. |
| **Agent Messages** | Triggered when the agent replies in the conversation. |

---

## Create an Omnichannel webhook

To create a new webhook in Rocket.Chat:

1. Navigate to **Manage** ![](https://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/2025-11-03_11-59-50.png) **> Omnichannel > Webhooks**.
2. Update the following fields:

| Field | Description |
| --- | --- |
| **Webhook URL** | The destination endpoint where Omnichannel data will be sent. |
| **Secret Token** | A secret key used to verify the request's origin. This token is sent in the request header `X-RocketChat-Livechat-Token`, allowing your endpoint to confirm the request is genuinely from Rocket.Chat. If your endpoint returns a response status other than `200`, Rocket.Chat will retry ten times, waiting ten seconds between retries. |
| **Send Request on** | Select the Omnichannel events that should send data to your configured webhook URL. See [Omnichannel webhook events](/v1/docs/webhooks#omnichannel-webhook-events) for a detailed list of available events. Whenever one of the selected events occurs, Rocket.Chat sends the metadata to your webhook. |
| **HTTP timeout (in milliseconds)** | Define how long Rocket.Chat waits for a response before considering the request failed. |
3. Click **Save** to apply the changes. You can click **Reset** to revert to the last saved changes.

Your webhook is now ready to receive real-time Omnichannel event data from Rocket.Chat. You can use these payloads to log chat activity or automate your workflows in your integrated systems.

> [!NOTE]
> - For example, you can set up a [Livechat trigger with an external service](/v1/docs/livechat-triggers#send-a-message-external-service) that is called after a specific condition is met.
> - The Webhook URL and Secret Token configured here are automatically populated in the main [CRM integration settings](/v1/docs/omnichannel-admins-guide#crm-integration).

---

## Testing the webhook

To verify the setup:

1. Click the **Send Test** button.
2. If successful, a message saying **It works** is displayed. Your configured webhook URL will receive a sample JSON payload containing the metadata similar to the example below:

```json
{
  "type": "LivechatSession",
  "_id": "fasd6f5a4sd6f8a4sdf",
  "label": "title",
  "topic": "asiodojf",
  "createdAt": "2025-11-05T12:20:36.190Z",
  "lastMessageAt": "2025-11-05T12:20:36.190Z",
  "tags": [
    "tag1",
    "tag2",
    "tag3"
  ],
  "customFields": {
    "productId": "123456"
  },
  "visitor": {
    "_id": "",
    "name": "visitor name",
    "username": "visitor-username",
    "department": "department",
    "email": "email@address.com",
    "phone": "192873192873",
    "ip": "123.456.7.89",
    "browser": "Chrome",
    "os": "Linux",
    "customFields": {
      "customerId": "123456"
    }
  },
  "agent": {
    "_id": "asdf89as6df8",
    "username": "agent.username",
    "name": "Agent Name",
    "email": "agent@email.com"
  },
  "messages": [
    {
      "username": "visitor-username",
      "msg": "message content",
      "ts": "2025-11-05T12:20:36.190Z"
    },
    {
      "username": "agent.username",
      "agentId": "asdf89as6df8",
      "msg": "message content from agent",
      "ts": "2025-11-05T12:20:36.190Z"
    }
  ]
}
```

---

## Sample JSON payload

Below are sample JSON payloads that demonstrate the data your webhook receives for common Omnichannel events:

Livechat sessionMessage sent

```json
{
  "_id": "Tc5SyBZHovD4k8BXv",
  "label": "James",
  "createdAt": "2023-02-02T10:16:07.230Z",
  "lastMessageAt": "2023-02-02T10:22:14.087Z",
  "tags": [
    "self"
  ],
  "visitor": {
    "_id": "63db8d4990fe6eda42ad429a",
    "token": "e36e352c742eee48860d576fcefb372afc44ebc95750fa1e3b646195f702341a",
    "name": "James",
    "username": "guest-3",
    "email": [
      {
        "address": "abc.xyz+local-on@rocket.chat"
      }
    ],
    "phone": null
  },
  "agent": {
    "_id": "aXjjcPwq4Pcp7xftH",
    "username": "user1",
    "name": "User One",
    "email": "uaser1@mail.com"
  },
  "type": "LivechatSession",
  "messages": [
    {
      "u": {
        "_id": "63db8d4990fe6eda42ad429a",
        "username": "guest-3",
        "name": "James"
      },
      "_id": "2untSdndqBP7opGWw",
      "username": "guest-3",
      "msg": "Hi",
      "ts": "2023-02-02T10:16:09.615Z"
    },
    {
      "u": {
        "_id": "aXjjcPwq4Pcp7xftH",
        "username": "user1",
        "name": "User One"
      },
      "_id": "7xjkw8ZFitMSNGmeJ",
      "username": "user1",
      "msg": "How can I help you today?",
      "ts": "2023-02-02T10:21:05.391Z",
      "agentId": "aXjjcPwq4Pcp7xftH"
    },
    {
      "u": {
        "_id": "63db8d4990fe6eda42ad429a",
        "username": "guest-3",
        "name": "James"
      },
      "_id": "y7p77YFfkHJeg5gD9",
      "username": "guest-3",
      "msg": "don't worry,thank you",
      "ts": "2023-02-02T10:22:14.087Z"
    },
    {
      "u": {
        "_id": "aXjjcPwq4Pcp7xftH",
        "username": "user1",
        "name": "User One"
      },
      "_id": "ciAggDuN8ioqDrTby",
      "username": "user1",
      "msg": "Thank you for visiting",
      "ts": "2023-02-02T10:23:11.437Z",
      "agentId": "aXjjcPwq4Pcp7xftH",
      "closingMessage": true
    }
  ],
  "servedBy": {
    "_id": "aXjjcPwq4Pcp7xftH",
    "username": "user1",
    "ts": "2023-02-02T10:16:07.375Z"
  },
  "closedAt": "2023-02-02T10:23:11.344Z",
  "closedBy": {
    "_id": "aXjjcPwq4Pcp7xftH",
    "username": "user1"
  },
  "closer": "user"
}
```

```json
{
  "_id": "Tc5SyBZHovD4k8BXv",
  "label": "James",
  "createdAt": "2023-02-02T10:16:07.230Z",
  "lastMessageAt": "2023-02-02T10:16:09.615Z",
  "visitor": {
    "_id": "63db8d4990fe6eda42ad429a",
    "token": "e36e352c742eee48860d576fcefb372afc44ebc95750fa1e3b646195f702341a",
    "name": "James",
    "username": "guest-3",
    "email": [
      {
        "address": "abc.xyz+local-on@rocket.chat"
      }
    ],
    "phone": null
  },
  "agent": {
    "_id": "aXjjcPwq4Pcp7xftH",
    "username": "user1",
    "name": "User One",
    "email": "uaser1@mail.com"
  },
  "type": "Message",
  "messages": [
    {
      "u": {
        "_id": "aXjjcPwq4Pcp7xftH",
        "username": "user1",
        "name": "User One"
      },
      "_id": "7xjkw8ZFitMSNGmeJ",
      "username": "user1",
      "msg": "How can I help you today?",
      "ts": "2023-02-02T10:21:05.391Z",
      "agentId": "aXjjcPwq4Pcp7xftH"
    }
  ]
}
```