- The Webhook API documentation provides comprehensive guidance on how to integrate and utilize Webhook functionality for real-time event-driven communication.
- Our platform is designed around the concept of event-driven communication. It allows your applications to subscribe to specific events and receive instant notifications when these events occur.
Please review the following requirements for setting up your webhook endpoint
- Your webhook endpoint must be accessible over HTTPS. This is essential to ensure the security and integrity of data transmission.
- Provide us with the URL where you’d like to receive webhook payloads. Webhook payloads would be in JSON format. This URL should be publicly accessible from the internet.
- Ensure that your endpoint supports the HTTP POST method. Webhook payloads will be delivered via HTTP POST requests.
- Configure your endpoint to respond immediately to the CometChat server with a 200 OK response.
- We recommend you use Basic Auth while configuring webhook, so as to validate incoming webhook requests.
| Parameters | Type | Description |
|---|---|---|
| id | string | Unique identifier of the webhook. It can have a maximum of 50 characters. |
| name | string | Display name of the webhook. It can have a maximum of 50 characters. |
| webhookURL | string | The webhookURL field represents the target URL to which webhook events will be delivered. |
| useBasicAuth | boolean | The useBasicAuth field is a boolean flag that indicates whether basic authentication should be applied when sending webhook requests to the specified webhookURL |
| username | string | This field should contain the username or identifier associated with the authentication credentials. |
| password | string | This field should contain the secret password that corresponds to the provided username. |
| enabled | boolean | The enabled field is a boolean flag that determines whether a webhook is currently active and capable of receiving and processing incoming events |
Constraints
| Item | Constraint | Notes |
|---|---|---|
| Maximum webhooks per app | 25 | Contact support if you need more |
| Webhook URL | 255 characters max | Must be a publicly accessible HTTPS endpoint |
| Webhook ID | 50 characters, alphanumeric (UTF8mb4, no spaces) | Unique identifier for managing the webhook |
| Authentication username | 50 characters, alphanumeric (no spaces) | Used for HTTP Basic Authentication |
| Authentication password | 100 characters, alphanumeric (no spaces) | Keep secure; used to verify webhook requests |
The list of triggers that are supported
| triggerId | Description |
|---|---|
message_sent | The hook triggers after the message is sent. |
message_edited | The hook triggers after the message is edited. |
message_deleted | The hook triggers after the message is deleted. |
message_reaction_added | The hook triggers after reaction is added to a message. |
message_reaction_removed | The hook triggers after reaction is removed from a message. |
user_blocked | The hook triggers when a user blocks another user. |
user_unblocked | The hook triggers when a user unblocks another user. |
group_created | The hook triggers after the group is created. |
group_updated | The hook triggers after the group is updated. |
group_deleted | The hook triggers after the group is deleted. |
group_member_joined | The hook triggers after a user joins a group. |
group_member_left | The hook triggers after a user leaves the group. |
group_member_added | The hook triggers after members are added to a group. |
group_member_kicked | The hook triggers after members are kicked from a group. |
group_member_banned | The hook triggers after members are banned from a group. |
group_member_unbanned | The hook triggers after members are unbanned from a group. |
group_member_scope_changed | The hook triggers if the scope of a member changes in a group. |
group_owner_transferred | The hook triggers if the owner of the group is changed. |
user_connection_status_changed | The hook triggers after a user connects/disconnects from the websocket server. |
message_delivery_receipt | The hook triggers when the client chat application confirms with Cometchat servers that a message was delivered. |
message_read_receipt | The hook triggers when the client chat application confirms with Cometchat servers that a message was read. |
call_initiated | The hook triggers when the call is initiated. |
call_started | The hook triggers when the call is started. |
call_participant_joined | The hook triggers when a participant joins the call. |
call_participant_left | The hook triggers when a participant leaves the call. |
call_ended | The hook triggers when the call is ended. |
meeting_started | The hook triggers when a meeting is started. |
meeting_participant_joined | The hook triggers when a participant joins the meeting. |
meeting_participant_left | The hook triggers when a participant leaves the meeting. |
meeting_ended | The hook triggers when the meeting is ended. |
recording_generated | The hook triggers when the recording is generated. |
Payload structure of events
Groups
group_created:
{
"trigger":"group_created",
"data":{
"group":{
"guid":"cometchat-guid-1",
"name":"Hiking Group",
"type":"public",
"scope":"admin",
"membersCount":1,
"joinedAt":1696932915,
"conversationId":"group_cometchat-guid-1",
"hasJoined":true,
"createdAt":1696932915,
"owner":"cometchat-uid-1"
},
"members":{
"cometchat-uid-1":{
"uid":"cometchat-uid-1",
"name":"Andrew Joseph",
"status":"available",
"role":"default",
"lastActiveAt":1696932834
}
}
},
"appId":"<appId>",
"region":"<region>",
"webhook":"<webhookID>"
}
group_updated:
{
"trigger": "group_updated",
"data": {
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 2,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695728507,
"owner": "cometchat-uid-2",
"updatedAt": 1696934048,
"updatedBy": "cometchat-uid-1",
"onlineMembersCount": 2
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_deleted:
{
"trigger": "group_deleted",
"data": {
"group": {
"guid": "cometchat-guid-1",
"name": "1234",
"type": "public",
"membersCount": 1,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695722912,
"owner": "cometchat-uid-1",
"updatedAt": 1695817083,
"updatedBy": "cometchat-uid-1",
"onlineMembersCount": 1
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_owner_transferred:
{
"trigger": "group_owner_transferred",
"data": {
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 2,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695728507,
"owner": "cometchat-uid-2",
"updatedAt": 1696933737,
"updatedBy": "cometchat-uid-1",
"onlineMembersCount": 2,
"oldOwner": "cometchat-uid-1"
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_added:
{
"trigger": "group_member_added",
"data": {
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 2,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1696932915,
"owner": "cometchat-uid-1",
"onlineMembersCount": 1
},
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "offline",
"role": "default",
"lastActiveAt": 1695751453,
"conversationId": "cometchat-uid-1_user_cometchat-uid-2"
}
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696932834
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_banned:
{
"trigger": "group_member_banned",
"data": {
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 1,
"conversationId": "group_group__1696932914913",
"createdAt": 1696932915,
"owner": "cometchat-uid-1",
"updatedAt": 1696933533,
"onlineMembersCount": 1
},
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "offline",
"role": "default",
"lastActiveAt": 1695751453,
"conversationId": "cometchat-uid-1_user_cometchat-uid-2"
}
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696932834
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_unbanned:
{
"trigger": "group_member_unbanned",
"data": {
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "offline",
"role": "default",
"lastActiveAt": 1695751453,
"conversationId": "cometchat-uid-1_user_cometchat-uid-2"
}
},
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 1,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1696932915,
"owner": "cometchat-uid-1",
"updatedAt": 1696933533,
"onlineMembersCount": 1
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696932834
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_joined:
{
"trigger": "group_member_joined",
"data": {
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696933689
}
},
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 2,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695728507,
"owner": "cometchat-uid-1",
"updatedAt": 1696933691,
"onlineMembersCount": 1
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_left:
{
"trigger": "group_member_left",
"data": {
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696933689
}
},
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 1,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695722891,
"owner": "cometchat-uid-1",
"updatedAt": 1696933827,
"onlineMembersCount": 1
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_scope_changed:
{
"trigger": "group_member_scope_changed",
"data": {
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696933928,
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"scope": "admin",
"oldScope": "participant"
}
},
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 2,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695722891,
"owner": "cometchat-uid-1",
"updatedAt": 1696933925,
"onlineMembersCount": 2
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696933934
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
group_member_kicked:
{
"trigger": "group_member_kicked",
"data": {
"members": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696933689,
"conversationId": "cometchat-uid-1_user_cometchat-uid-2"
}
},
"group": {
"guid": "cometchat-guid-1",
"name": "Hiking Group",
"type": "public",
"membersCount": 1,
"conversationId": "group_cometchat-guid-1",
"createdAt": 1695722891,
"owner": "cometchat-uid-1",
"updatedAt": 1696933889,
"onlineMembersCount": 8
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696933881
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
Messages
message_sent:
{
"trigger": "message_sent",
"data": {
"message": {
"id": "1",
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"sender": "cometchat-uid-1",
"receiverType": "user",
"receiver": "cometchat-uid-2",
"category": "message",
"type": "text",
"data": {
"text": "hi",
"entities": {
"sender": {
"entity": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696934440
},
"entityType": "user"
},
"receiver": {
"entity": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"avatar": "https://example.com/avatars/george-alan.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696934491,
"conversationId": "cometchat-uid-1_user_cometchat-uid-2"
},
"entityType": "user"
}
}
},
"sentAt": 1696934912,
"updatedAt": 1696934912
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
message_edited:
{
"trigger": "message_edited",
"data": {
"message": {
"id": "2",
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"sender": "cometchat-uid-1",
"receiverType": "user",
"receiver": "cometchat-uid-2",
"category": "action",
"type": "message",
"data": {
"action": "edited",
"entities": {
"by": {
"entity": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"avatar": "https://example.com/avatars/andrew-joseph.png",
"status": "available",
"role": "default",
"lastActiveAt": 1696934440
},
"entityType": "user"
},
"on": {
"entity": {
"id": "1",
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"sender": "cometchat-uid-1",
"receiverType": "user",
"receiver": "cometchat-uid-2",
"category": "message",
"type": "text",
"data": {
"text": "hello"
},
"sentAt": 1696934912,
"editedAt": 1696934985,
"editedBy": "cometchat-uid-1"
},
"entityType": "message"
}
}
},
"sentAt": 1696934985,
"updatedAt": 1696934985
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
message_deleted:
{
"trigger": "message_deleted",
"data": {
"message": {
"id": "3",
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"sender": "cometchat-uid-1",
"receiverType": "user",
"receiver": "cometchat-uid-2",
"category": "action",
"type": "message",
"data": {
"action": "deleted",
"entities": {
"by": {
"entity": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph"
},
"entityType": "user"
},
"on": {
"entity": {
"id": "2",
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"deletedAt": 1696935005,
"deletedBy": "cometchat-uid-1"
},
"entityType": "message"
}
}
},
"sentAt": 1696935005,
"updatedAt": 1696935005
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
message_delivery_receipt:
{
"trigger": "message_delivery_receipt",
"data": {
"receiver": "cometchat-uid-1",
"receiverType": "user",
"type": "receipts",
"sender": "cometchat-uid-2",
"messageSender": "cometchat-uid-1",
"body": {
"action": "delivered",
"messageId": "57",
"user": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"status": "online"
},
"timestamp": 1696934912
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
message_read_receipt:
{
"trigger": "message_read_receipt",
"data": {
"receiver": "cometchat-uid-1",
"receiverType": "user",
"type": "receipts",
"sender": "cometchat-uid-2",
"messageSender": "cometchat-uid-1",
"body": {
"action": "read",
"messageId": "57",
"user": {
"uid": "cometchat-uid-2",
"name": "George Alan",
"status": "online"
},
"timestamp": 1696934950
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
message_reaction_added:
{
"trigger": "message_reaction_added",
"data": {
"reaction": {
"id": "<reactionId>",
"messageId": "<messageId>",
"reaction": "🏒",
"uid": "cometchat-uid-1",
"reactedAt": 1700655536,
"reactedBy": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph"
}
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
message_reaction_removed:
{
"trigger": "message_reaction_removed",
"data": {
"reaction": {
"id": "<reactionId>",
"messageId": "<messageId>",
"reaction": "🏒",
"uid": "cometchat-uid-1",
"reactedAt": 1700231289,
"reactedBy": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph"
}
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
Users
user_connection_status_changed:
{
"trigger": "user_connection_status_changed",
"data": {
"timestamp": 1696935103114,
"user": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph",
"status": "offline",
"role": "default"
},
"status": "offline",
"currentConnection": {
"action": "disconnected",
"platform": "javascript",
"connectedAt": 1696934440982
},
"userPresenceChanged": true
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
user_blocked:
{
"trigger": "user_blocked",
"data": {
"users": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan"
}
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph"
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
user_unblocked:
{
"trigger": "user_unblocked",
"data": {
"users": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "George Alan"
}
},
"by": {
"uid": "cometchat-uid-1",
"name": "Andrew Joseph"
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
user_mentioned:
{
"trigger": "user_mentioned",
"data": {
"message": {
"id": "4",
"conversationId": "cometchat-uid-1_user_cometchat-uid-2",
"sender": "cometchat-uid-1",
"receiverType": "user",
"receiver": "cometchat-uid-2",
"category": "message",
"type": "text",
"data": {
"text": "Hi <@uid:cometchat-uid-2>",
"mentions": {
"cometchat-uid-2": {
"uid": "cometchat-uid-2",
"name": "Andrew Joseph"
}
}
},
"sentAt": 1702028666,
"updatedAt": 1702028666
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
Calls & Meetings
call_initiated:
{
"trigger": "call_initiated",
"data": {
"call": {
"id": "52",
"conversationId": "cometchat-uid-1_user_cometchat-uid-5",
"sender": "cometchat-uid-1",
"receiverType": "user",
"receiver": "cometchat-uid-5",
"category": "call",
"type": "audio",
"data": {
"action": "initiated"
},
"sentAt": 1696934199,
"updatedAt": 1696934199
}
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
call_started:
{
"trigger": "call_started",
"data": {
"created_at": 1696934572,
"sessionId": "<sessionId>"
},
"type": "call",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
call_ended:
{
"trigger": "call_ended",
"data": {
"all_occupants": [
{
"joined_at": 1696934501,
"audio_call": "true",
"left_at": 1696934553,
"name": "George Alan"
},
{
"joined_at": 1696934501,
"audio_call": "true",
"left_at": 1696934551,
"name": "Andrew Joseph"
}
],
"destroyed_at": 1696934553,
"created_at": 1696934501,
"sessionId": "<sessionId>"
},
"type": "call",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
call_participant_joined:
{
"trigger": "call_participant_joined",
"data": {
"occupant": {
"joined_at": 1696934573,
"audio_call": "true",
"name": "Andrew Joseph"
},
"sessionId": "<sessionId>"
},
"type": "call",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
call_participant_left:
{
"trigger": "call_participant_left",
"data": {
"occupant": {
"joined_at": 1696934501,
"audio_call": "true",
"left_at": 1696934553,
"name": "George Alan"
},
"sessionId": "<sessionId>"
},
"type": "call",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
meeting_started:
{
"trigger": "meeting_started",
"data": {
"created_at": 1696934692,
"sessionId": "<sessionId>"
},
"type": "meet",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
meeting_participant_joined:
{
"trigger": "meeting_participant_joined",
"data": {
"occupant": {
"joined_at": 1696934692,
"audio_call": "false",
"name": "Andrew Joseph"
},
"sessionId": "<sessionId>"
},
"type": "meet",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
meeting_participant_left:
{
"trigger": "meeting_participant_left",
"data": {
"occupant": {
"joined_at": 1696934692,
"audio_call": "false",
"left_at": 1696934730,
"name": "Andrew Joseph"
},
"sessionId": "<sessionId>"
},
"type": "meet",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
meeting_ended:
{
"trigger": "meeting_ended",
"data": {
"all_occupants": [
{
"joined_at": 1696934692,
"audio_call": "false",
"left_at": 1696934730,
"name": "Andrew Joseph"
}
],
"destroyed_at": 1696934730,
"created_at": 1696934692,
"sessionId": "<sessionId>"
},
"type": "meet",
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}
recording_generated:
{
"trigger": "recording_generated",
"data": {
"recordingDate": "2023-10-10",
"duration": "21.433000",
"startTime": "1696937627",
"sessionId": "<sessionId>",
"recording_url": "<recording_url>"
},
"appId": "<appId>",
"region": "<region>",
"webhook": "<webhookID>"
}