This is legacy documentation. It is no longer actively maintained. For current docs, visit cometchat.com/docs.

Webhooks (Legacy)

Legacy Notice: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements.

For new projects, use Webhooks.

CometChat legacy webhooks enable real-time event-driven communication with your system. They allow you to receive HTTP POST requests whenever specific events occur—such as sending a message or a user coming online. These webhooks are ideal for integrating external services like SMS, email, analytics, or auditing systems.

Webhook Endpoint Requirements

To ensure reliable delivery and security, your webhook endpoint must meet the following requirements:

  1. HTTPS required: Your endpoint must use HTTPS to ensure secure data transmission.
  2. Public accessibility: It must be accessible from the public internet.
  3. Support for POST requests: The endpoint must accept HTTP POST requests with a Content-Type of application/json.
  4. Immediate acknowledgment: Your server must respond with an HTTP 200 OK status quickly to acknowledge receipt.

Security

It is strongly recommended to use Basic Authentication to protect your webhook endpoints.

Header format

When enabled, every webhook request from CometChat will include the following HTTP header:

Authorization: Basic <Base64-encoded-credentials>

Set your username and password while configuring the webhook on the CometChat dashboard.

Legacy webhook events

Below are the legacy webhook events supported by CometChat:

Event Description
before_message Triggered when a message is in-flight—just before it is processed by CometChat.
after_message Triggered after a message has been successfully sent.
message_delivery_receipt Triggered when a message is marked as delivered to a user.
message_read_receipt Triggered when a message is marked as read by the recipient.
user_connection_status_change Triggered when a user connects or disconnects from the CometChat platform.

Manage legacy webhooks

You can manage and configure legacy webhooks in CometChat either from the dashboard UI or programmatically via Management APIs.

Option 1: Manage from the dashboard

Steps

  1. Log in to your CometChat Dashboard and select your app.
  2. Go to Settings > Legacy Webhooks from the left menu.
  3. Click on Add New Webhook.
  4. Fill in the configuration:
  5. Webhook ID: A unique identifier for your webhook.
  6. URL: Endpoint where event payloads will be delivered.
  7. Triggers: Select the events you want to receive.
  8. Security: (Recommended) Enable authentication.
  9. Enable the webhook.
  10. Save the configuration.

Option 2: Manage via Management APIs

CometChat also provides Management APIs to automate webhook and trigger management.

Webhook management endpoints

Operation API Reference
Create a new webhook Create Webhook
Update an existing webhook Update Webhook
List all webhooks List Webhooks
Get a webhook by ID Get Webhook
Delete a webhook Delete Webhook

Trigger management endpoints

Operation API Reference
Add triggers to a webhook Add Triggers
List all triggers of a webhook List Triggers
Remove triggers from a webhook Remove Triggers

Event payloads

Message events

before_message

The endpoint will be triggered when a message is in-flight.

{
    "trigger": "before_message",
    "data": {
        "conversationId": "cometchat-uid-4_user_cometchat-uid-5",
        "sender": "cometchat-uid-5",
        "receiverType": "user", 
        "receiver": "cometchat-uid-4",
        "category": "message",
        "type": "text",
        "data": {
            "text": "Hi Webhook Test",
            "entities": {
                "sender": {
                    "entity": {
                        "uid": "cometchat-uid-5",
                        "name": "John Paul",
                        "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-5.webp",
                        "status": "offline",
                        "role": "default"
                    },
                    "entityType": "user"
                },
                "receiver": {
                    "entity": {
                        "uid": "cometchat-uid-4",
                        "name": "Susan Marie",
                        "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-4.webp",
                        "status": "offline",
                        "role": "default"
                    },
                    "entityType": "user"
                }
            }
        },
        "sentAt": 1586435925,
        "updatedAt": 1586435925,
    },
    "appId": "167*****1529",
    "webhook": "send-message"
}

after_message

The endpoint will be triggered after a message is sent.

{
    "trigger": "after_message",
    "data": {
        "id": "1",
        "conversationId": "cometchat-uid-4_user_cometchat-uid-5",
        "sender": "cometchat-uid-5",
        "receiverType": "user", 
        "receiver": "cometchat-uid-4",
        "category": "message",
        "type": "text",
        "data": {
            "text": "Hi Webhook Test",
            "entities": {
                "sender": {
                    "entity": {
                        "uid": "cometchat-uid-5",
                        "name": "John Paul",
                        "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-5.webp",
                        "status": "offline",
                        "role": "default"
                    },
                    "entityType": "user"
                },
                "receiver": {
                    "entity": {
                        "uid": "cometchat-uid-4",
                        "name": "Susan Marie",
                        "avatar": "https://assets.cometchat.io/sampleapp/v2/users/cometchat-uid-4.webp",
                        "status": "offline",
                        "role": "default"
                    },
                    "entityType": "user"
                }
            }
        },
        "sentAt": 1586435925,
        "updatedAt": 1586435925,
    },
    "appId": "167*****1529",
    "webhook": "send-message"
}

message_delivery_receipt

The endpoint will be triggered when a message is marked delivered.

{
  "trigger": "message_delivery_receipt",
  "appId": "167*****1529",
  "origin": {
      "platform": "WEBSOCKET"
  },
  "chatAPIVersion?": "3.0", 
  "region?": "us|eu|other",
  "webhook": "webhook_name",
    "data": {
    "messageId": "MESSAGE_ID",
    "receiptType": "delivered",
    "deliveredAt": 1673017183,
    "messageSender":"messageSenderUID",
    "receiptSender":"receiptSenderUID",
    "receiptReceiver":"uid|guid",
    "receiverType": "user|group"
  }
}

message_read_receipt

The endpoint will be triggered when a message is marked read.

{
  "trigger": "message_read_receipt",
  "appId": "167*****1529",
  "origin": {
    "platform": "WEBSOCKET"
  },
  "chatAPIVersion?": "3.0",
  "region?": "us|eu|other",
  "webhook": "webhook_name",
    "data": {
    "messageId": "MESSAGE_ID",
    "receiptType": "read",
    "readAt": 1673017183,
    "messageSender":"messageSenderUID",
    "receiptSender":"receiptSenderUID",
    "receiptReceiver":"uid|guid",
    "receiverType": "user|group"
  }
}

user_connection_status_change

The endpoint will be triggered when a users logs in or logs out of CometChat.

{
  "trigger": "after_connection_status_changed",
  "appId": "167*****1529",
  "origin": {
    "platform": "API|MGNT-API|WEBSOCKET|WEBRTC"
  },
  "chatAPIVersion?": "3.0",
  "region?": "us|eu|other",
  "webhook": "webhook_name",
  "data": {
    "user": {
      "uid": "uid of the user",
      "status": "online|offline",
      "status_updated": true,
      "status_updated_at": "unixtimestamp in millisec"
    },
    "event": {
      "type": "connected|disconnected",
      "at": "unixtimestamp in millisec",
      "event_for": {
        "connected_at": "unixtimestamp in millisec",
        "cometchat_device_id": "unique device id used by cometchat to identify the device(random string)",
        "session_id": "unique id to indetify the unique session of users",
        "platform": "android|ios|web"
      }
    },
    "connections": [
      {
        "connected_at": "unixtimestamp in millisec",
        "cometchat_device_id": "unique device id used by cometchat to identify the device(random string)",
        "session_id": "unique id to indetify the unique session of users",
        "platform": "android|ios|web"
      },
      {
        "connected_at": "unixtimestamp in millisec",
        "cometchat_device_id": "unique device id used by cometchat to identify the device(random string)",
        "session_id": "unique id to indetify the unique session of users",
        "platform": "android|ios|web"
      }
    ]
  }
}