> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-audit-content-webhooks.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```json theme={null}
{
  "@injected": {
    "webhooks": {
      "webhook-id": {
        // JSON object returned from your endpoint
      }
    }
  }
}
```

It can also **drop the message** entirely by returning:

```json theme={null}
{
  "action": "do_not_propagate"
}
```

## Getting Started

<Steps>
  <Step title="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.
  </Step>

  <Step title="Test it locally with a tunnel">
    Expose your local server with a tunneling tool such as [ngrok](https://ngrok.com) so CometChat can reach it during development:

    ```bash theme={null}
    ngrok http 8000
    ```

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

  <Step title="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](/rest-api/management-apis/webhooks/create-webhook).
  </Step>
</Steps>

For the full setup walkthrough and per-platform payloads, see the SDK webhooks guides — for example [JavaScript](/sdk/javascript/webhooks) or [Android](/sdk/android/v5/webhooks-overview) — and the [Webhooks REST APIs](/rest-api/management-apis/webhooks/overview).

<Note>
  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.
</Note>