> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook

> Register an HTTPS endpoint to receive Connectly webhook events for a given topic 💪

Register a URL that Connectly will POST to whenever a subscribed event occurs. You can register one address per topic.

## Endpoint

```json theme={null}
POST https://api.connectly.ai/v1/businesses/{businessId}/create/webhooks
```

## Request body

<ParamField body="topic" type="string" required>
  The event topic to subscribe to.

  | Value             | Description                                                              |
  | ----------------- | ------------------------------------------------------------------------ |
  | `messages`        | Inbound WhatsApp messages sent by your customers.                        |
  | `delivery_status` | Delivery status updates: `sent`, `delivered`, `read`, `delivery_failed`. |
</ParamField>

<ParamField body="address" type="string" required>
  Your publicly accessible HTTPS endpoint URL (e.g. `https://example.com/webhook`).
</ParamField>

<ParamField body="type" type="string">
  Integration type for this webhook. Defaults to `custom`.

  | Value             | Description                    |
  | ----------------- | ------------------------------ |
  | `custom`          | Your own HTTP endpoint.        |
  | `zapier`          | Zapier integration.            |
  | `webengage`       | WebEngage integration.         |
  | `integromat_make` | Integromat / Make integration. |
</ParamField>

<ParamField body="configuration" type="object">
  Advanced configuration options.

  <Expandable title="configuration properties">
    <ParamField body="echo" type="boolean">
      When `true`, outbound messages sent by your business are echoed back to this webhook in addition to inbound messages.
    </ParamField>

    <ParamField body="channelTypes" type="array">
      List of channel types to filter events by (e.g. `["whatsapp"]`). When omitted, events from all channels are delivered.
    </ParamField>

    <ParamField body="filters" type="array">
      List of filter rules to restrict which events are delivered.

      <Expandable title="filter properties">
        <ParamField body="field" type="string">
          The event field to match on (e.g. `campaign_name`).
        </ParamField>

        <ParamField body="expression" type="string">
          Glob-style expression to match against the field value (e.g. `summer-promo-*`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="webengageConfiguration" type="object">
      Required when `type` is `webengage`.

      <Expandable title="webengageConfiguration properties">
        <ParamField body="webengageToken" type="string">
          Your WebEngage API token.
        </ParamField>

        <ParamField body="webengageWebhookUrl" type="string">
          Your WebEngage webhook URL.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Examples

<AccordionGroup>
  <Accordion title="Register for inbound messages">
    ```bash theme={null}
    curl --request POST \
      --url https://api.connectly.ai/v1/businesses/{businessId}/create/webhooks \
      --header 'Content-Type: application/json' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --data '{
        "topic": "messages",
        "address": "https://example.com/webhook/messages"
      }'
    ```
  </Accordion>

  <Accordion title="Register for delivery status">
    ```bash theme={null}
    curl --request POST \
      --url https://api.connectly.ai/v1/businesses/{businessId}/create/webhooks \
      --header 'Content-Type: application/json' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --data '{
        "topic": "delivery_status",
        "address": "https://example.com/webhook/delivery"
      }'
    ```
  </Accordion>

  <Accordion title="With campaign filter and channel type">
    ```bash theme={null}
    curl --request POST \
      --url https://api.connectly.ai/v1/businesses/{businessId}/create/webhooks \
      --header 'Content-Type: application/json' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --data '{
        "topic": "delivery_status",
        "address": "https://example.com/webhook/delivery",
        "configuration": {
          "channelTypes": ["whatsapp"],
          "filters": [
            { "field": "campaign_name", "expression": "summer-promo-*" }
          ]
        }
      }'
    ```
  </Accordion>
</AccordionGroup>

## Response

```json theme={null}
{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }
```

Save the returned `id` — you'll need it to [update](/webhooks/update-webhook) or [delete](/webhooks/delete-webhook) this registration.

## Error responses

| Status | Meaning                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------- |
| `400`  | Malformed body or invalid field values.                                                                    |
| `401`  | Missing or invalid `X-API-Key`.                                                                            |
| `409`  | An endpoint is already registered for this topic — use [Update webhook](/webhooks/update-webhook) instead. |
| `500`  | Internal server error.                                                                                     |