Webhooks

Use CometChat webhooks to send real-time chat, user, group, call, and moderation events to your server.

CometChat Webhooks enable real-time, event-driven communication with your server by sending HTTP POST requests whenever specific events occur in your chat application.

What Are Webhooks?

Webhooks are automated notifications that CometChat sends to your server when events happen—such as messages being sent, users coming online, or group membership changes. Instead of polling for updates, your server receives instant notifications, enabling real-time integrations.

Common Use Cases

Webhooks enable you to build powerful integrations and automations:

• Notifications: Send SMS, email, or push notifications when users receive messages
• Analytics: Track messaging activity and user engagement in your analytics platform
• Moderation: Trigger content review workflows when messages are flagged
• Sync: Keep external systems (CRM, support tools, databases) in sync with chat activity
• Automation: Trigger business workflows based on chat events

Supported Events

CometChat webhooks cover a comprehensive range of events across different categories:

Message Events

Notifications for message lifecycle events including sent, edited, deleted, delivered, read, and reactions.

User Events

Notifications for user actions such as blocking/unblocking users and connection status changes (online/offline).

Group Events

Notifications for group lifecycle and membership events including creation, updates, member joins/leaves, bans, and scope changes.

Call and Meeting Events

Notifications for voice/video call events including initiation, start, end, participant joins/leaves, and recording generation.

Moderation Events

Notifications for content moderation outcomes including auto-approved, auto-blocked, and manually approved messages.

Campaign Events

Notifications for campaign lifecycle events including campaign completion, failure, notification creation, feed item delivery (sent, delivered, read, interacted), and push notification delivery (sent, delivered, clicked).

Webhook Requirements

Your webhook endpoint must:

• Use HTTPS for secure communication
• Be publicly accessible from the internet
• Accept HTTP POST requests with JSON content
• Respond with HTTP 200 OK to acknowledge receipt

Security

CometChat supports Basic Authentication to secure your webhook endpoints. When configured, every webhook request includes an Authorization header with your credentials, ensuring only authorized requests are processed.

Best Practices

• Handle retries gracefully: Use event IDs to deduplicate retried deliveries
• Respond quickly: Return 200 OK within 2 seconds; queue longer processing tasks
• Log everything: Maintain detailed logs for debugging and monitoring
• Test thoroughly: Simulate various conditions before going to production

Message Triggers

For message events you choose when CometChat calls your endpoint:

Trigger	When it fires	Typical use
after_message	After a message has been sent and delivered.	Notifications, analytics, syncing external systems.
before_message	While a message is in-flight, before it reaches the recipient.	Enrich, validate, or block a message before delivery.

A before_message endpoint can add metadata to the message by returning a JSON object. CometChat merges your response into the message under @injected.webhooks:

{
  "@injected": {
    "webhooks": {
      "webhook-id": {
        // JSON object returned from your endpoint
      }
    }
  }
}

It can also drop the message entirely by returning:

{
  "action": "do_not_propagate"
}

Getting Started

1. Create an endpoint on your server

   Add a route that accepts an HTTP POST with a JSON body and returns 200 OK. This is no different from adding any other route in your web framework.

2. Test it locally with a tunnel

   Expose your local server with a tunneling tool such as ngrok so CometChat can reach it during development:

   ngrok http 8000
   

   Use the HTTPS forwarding URL it prints (e.g. https://xxxx.ngrok.io) as your webhook destination.

3. Register the webhook

   In the Dashboard’s Webhooks section choose Create Webhook, enter your endpoint URL, then open View/Update to add a trigger. You can also create webhooks programmatically with the Create Webhook REST API.

For the full setup walkthrough and per-platform payloads, see the SDK webhooks guides — for example JavaScript or Android — and the Webhooks REST APIs.

Retry/backoff behaviour and request-signature verification beyond Basic Authentication are not documented here — confirm the current behaviour with the CometChat team before relying on it in production.