CometChat Webhooks enable real-time, event-driven communication with your server by sending HTTP POST requests for specific events such as messages, user actions, group updates, calls, and moderation results. You can use webhooks to build custom workflows such as sending SMS or email notifications, logging activity, syncing with external systems, or triggering automation.

​
Setting Up Your Webhook Endpoint

To successfully receive and process events from CometChat, your webhook endpoint must meet the following criteria:
  1. Use HTTPS – All webhook URLs must be secured with SSL.
  2. Be publicly accessible – Your server should be reachable from the internet.
  3. Support POST method – Events will be delivered as HTTP POST requests with application/json content.
  4. Return a 200 OK – Your endpoint must acknowledge receipt by responding with HTTP 200.

​
Securing Your Webhook

To ensure only authorized systems can access your endpoint, use Basic Authentication: 
Authorization: Basic <Base64-encoded-credentials>
You can configure this with a username and password known only to your system.

​
Token-based files access

Token-based file access provides improved control over media files through pre-signed URLs. When this feature is enabled, media URLs in webhook payloads may return a 401 Unauthorized response. You can enable this feature in the Settings section under Chats in the CometChat dashboard. Once enabled, it cannot be disabled.
To access media files, use the media URL from the webhook payload to obtain a URL secured with a file access token (FAT). This URL redirects to a pre-signed URL that remains valid for 5 minutes. Sample request: 
curl --location 'https://files-<REGION>.cometchat.io/<APP_ID>/media/audio3.mp3' \
  --header 'appId: <APP_ID>' \
  --header 'apiKey: <API_KEY>'
Sample response: 
{
  "data": {
    "url": "https://files-<REGION>.cometchat.io/<APP_ID>/media/audio3.mp3?fat=<FILE_ACCESS_TOKEN>"
  }
}

​
Webhook Best Practices

To maximize reliability and avoid common issues, follow these recommendations:

​
1. Handle Retries Gracefully

  • Use the retryOnFailure flag when setting up webhooks.
  • If enabled, CometChat retries failed deliveries:
    • First retry: after 10 seconds.
    • Second retry: after 30 seconds.
  • Use unique event IDs from payloads to deduplicate retries.

​
2. Respond Quickly

  • Respond within 2 seconds to prevent timeouts.
  • For long processing tasks, enqueue events to systems like Kafka, RabbitMQ, or AWS SQS, and process them asynchronously.

​
3. Log and Monitor

  • Maintain detailed logs of all incoming webhook requests and your server responses.
  • Track failures, latency, and retry attempts.

​
4. Implement Robust Error Handling

  • Return appropriate HTTP status codes:
    • 200 OK for success.
    • 4xx for client-side errors (e.g., bad request).
    • 5xx for server-side issues.

​
5. Thoroughly Test Before Production

  • Simulate various conditions: successful delivery, retries, and failures.
  • Ensure your implementation handles all cases gracefully.

​
Webhook Event Triggers

CometChat supports webhook triggers for different categories of events. Click each event name to see its payload and details.

​
Message Events

EventDescription
message_sentTriggered after a message is sent.
message_editedTriggered after a message is edited.
message_deletedTriggered after a message is deleted.
message_delivery_receiptTriggered when a message is delivered to the client.
message_read_receiptTriggered when a message is marked as read.
message_reaction_addedTriggered when a user reacts to a message.
message_reaction_removedTriggered when a reaction is removed.
user_mentionedTriggered when a user is mentioned in a message.

​
User Events

EventDescription
user_blockedTriggered when a user blocks another user.
user_unblockedTriggered when a user unblocks another user.
user_connection_status_changedTriggered when a user connects/disconnects.

​
Group Events

EventDescription
group_createdTriggered after a group is created.
group_updatedTriggered after a group is updated.
group_deletedTriggered after a group is deleted.
group_member_addedTriggered when a member is added.
group_member_removedTriggered when a member is removed.
group_member_bannedTriggered when a member is banned.
group_member_unbannedTriggered when a member is unbanned.
group_member_joinedTriggered when a user joins a group.
group_member_leftTriggered when a user leaves a group.
group_member_kickedTriggered when a member is kicked.
group_member_scope_changedTriggered when a member’s scope changes.
group_owner_transferredTriggered when group ownership is transferred.

​
Call and Meeting Events

EventDescription
call_initiatedTriggered when a call is initiated.
call_startedTriggered when a call starts.
call_endedTriggered when a call ends.
call_participant_joinedTriggered when a participant joins a call.
call_participant_leftTriggered when a participant leaves a call.
call_busyThis hook is triggered when a 1-on-1 call cannot be connected because the recipient is already on another call (i.e., their line is busy).
call_cancelledThe hook triggers when the call is cancelled.
call_rejectedThis hook is triggered when a 1-on-1 call is explicitly rejected by the recipient.
call_unansweredThis hook is triggered when a call goes unanswered.
meeting_startedTriggered when a meeting starts.
meeting_endedTriggered when a meeting ends.
meeting_participant_joinedTriggered when a participant joins a meeting.
meeting_participant_leftTriggered when a participant leaves a meeting.
recording_generatedTriggered when a recording is generated.

​
Moderation Events

EventDescription
moderation_engine_approvedTriggered when a message is auto-approved.
moderation_engine_blockedTriggered when a message is auto-blocked.
moderation_manual_approvedTriggered when a blocked message is manually approved.
By following this guide, you can seamlessly integrate CometChat webhooks into your system and build event-driven experiences at scale.