The Omnichannel Webhooks feature allows you to integrate your Omnichannel events with any third-party system, 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.
Omnichannel Webhook events
Below is a list of the available Omnichannel events you can select to send data to your configured webhook URL:
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:
Navigate to Manage
> Omnichannel > Webhooks. 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.
HTTP timeout (in milliseconds)
Define how long Rocket.Chat waits for a response before considering the request failed.
Click Save to apply the changes. You can click Reset to revert to the last saved changes
The Webhook URL and Secret Token configured here are automatically populated in the main CRM integration settings.
Testing the webhook
To verify the setup:
Click the Send Test button.
If successful, a message saying "It works" is displayed. Your configured webhook URL will receive a sample JSON payload 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 recieves 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"
}
]
}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.