Webhooks Overview

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

Basic Authentication (Recommended)

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.

Secure Media File Access

Webhook payloads may include media URLs. Direct access to these URLs will return 401 Unauthorized. To fetch media, use a pre-signed URL:

Sample request:

curl --location 'https://files-<REGION>.cometchat.io/<APP_ID>/media/audio3.mp3?redirect=0' \
  --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>"
  }
}

The generated pre-signed URL is valid for 5 minutes.

---

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

Event	Description
message_sent	Triggered after a message is sent.
message_edited	Triggered after a message is edited.
message_deleted	Triggered after a message is deleted.
message_delivery_receipt	Triggered when a message is delivered to the client.
message_read_receipt	Triggered when a message is marked as read.
message_reaction_added	Triggered when a user reacts to a message.
message_reaction_removed	Triggered when a reaction is removed.
user_mentioned	Triggered when a user is mentioned in a message.

---

User Events

Event	Description
user_blocked	Triggered when a user blocks another user.
user_unblocked	Triggered when a user unblocks another user.
user_connection_status_changed	Triggered when a user connects/disconnects.

---

Group Events

Event	Description
group_created	Triggered after a group is created.
group_updated	Triggered after a group is updated.
group_deleted	Triggered after a group is deleted.
group_member_added	Triggered when a member is added.
group_member_removed	Triggered when a member is removed.
group_member_banned	Triggered when a member is banned.
group_member_unbanned	Triggered when a member is unbanned.
group_member_joined	Triggered when a user joins a group.
group_member_left	Triggered when a user leaves a group.
group_member_kicked	Triggered when a member is kicked.
group_member_scope_changed	Triggered when a member's scope changes.
group_owner_transferred	Triggered when group ownership is transferred.

---

Call and Meeting Events

Event	Description
call_initiated	Triggered when a call is initiated.
call_started	Triggered when a call starts.
call_ended	Triggered when a call ends.
call_participant_joined	Triggered when a participant joins a call.
call_participant_left	Triggered when a participant leaves a call.
call_busy	This 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_cancelled	The hook triggers when the call is cancelled.
call_rejected	This hook is triggered when a 1-on-1 call is explicitly rejected by the recipient.
call_unanswered	This hook is triggered when a call goes unanswered.
meeting_started	Triggered when a meeting starts.
meeting_ended	Triggered when a meeting ends.
meeting_participant_joined	Triggered when a participant joins a meeting.
meeting_participant_left	Triggered when a participant leaves a meeting.
recording_generated	Triggered when a recording is generated.

---

Moderation Events

Event	Description
moderation_engine_approved	Triggered when a message is auto-approved.
moderation_engine_blocked	Triggered when a message is auto-blocked.
moderation_manual_approved	Triggered 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.