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:

Create an Omnichannel webhook

To create a new webhook in Rocket.Chat:

1. Navigate to Manage > 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 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.

• For example, you can set up a Livechat trigger with an 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.

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:

   {
     "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:

{
  "_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"
}

{
  "_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"
    }
  ]
}