> ## 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.

# Webhooks Overview

> Register an HTTPS endpoint to receive real-time WhatsApp events from Connectly — inbound messages, delivery status updates, and HMAC-SHA256 verification 🛜

Connectly webhooks deliver real-time WhatsApp events — inbound customer messages and outbound delivery status updates — directly to an HTTPS endpoint you control. Once you register your endpoint for a topic, Connectly POSTs event payloads to it as they occur.

## Available topics

| Topic             | Description                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| `messages`        | Inbound WhatsApp messages sent to your business number by customers.                              |
| `delivery_status` | Delivery status updates for messages you sent: `sent`, `delivered`, `read`, or `delivery_failed`. |

<Note>
  You can only register **one endpoint address per topic**. Creating a new registration for an existing topic replaces the current one. To change the address for an active topic, use [Update webhook](https://docs.connectly.ai/api-reference/update-webhook) rather than deleting and recreating, to avoid a gap in event delivery.
</Note>

***

## Register your endpoint

Before you start receiving events, register your endpoint for the topic you want:

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

Change `"topic"` to `"delivery_status"` and update `"address"` to register for delivery status events instead. See [Create webhook](https://docs.connectly.ai/api-reference/create-webhook) for the full reference.

***

## Verify HMAC signatures

Every webhook request Connectly sends includes an `x-connectly-hmac-sha256` header — a Base64-encoded HMAC-SHA256 digest of the raw request body, signed with your webhook secret. Always verify this before processing the payload.

```go theme={null}
secret := "YOUR_SECRET_VALUE"
data := string(webhookEventBody)
hash := hmac.New(sha256.New, []byte(secret))
hash.Write([]byte(data))
isValid := webhookEventHMAC == base64.StdEncoding.EncodeToString(hash.Sum(nil))
```

<Warning>
  Reject any request where the computed HMAC does not match the `x-connectly-hmac-sha256` header. Never process unauthenticated webhook payloads.
</Warning>

***

## Acknowledge receipt

Your endpoint must return HTTP `200` for every event to acknowledge successful delivery. Connectly treats any non-200 response as a failure and may retry the request.

***

## Delivery status event flow

When you send a message via the Connectly API, the response includes a message ID:

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

Delivery status events include this same ID in `statusUpdate.id`, so you can correlate each status update back to the original outbound message. The typical progression for a successfully delivered and read message is:

<Steps>
  <Step title="sent">
    The message was dispatched to the recipient. Delivery is not yet confirmed.
  </Step>

  <Step title="delivered">
    The message reached the recipient's device. It may not have been opened yet.
  </Step>

  <Step title="read">
    The recipient opened the message in their WhatsApp app.
  </Step>

  <Step title="delivery_failed">
    The message could not be delivered. The event includes an `error` object with a `cntTraceId` you can share with Connectly support.
  </Step>
</Steps>

<Tip>
  Store the message ID returned when you send a message so you can match it against incoming `delivery_status` events via the `statusUpdate.id` field.
</Tip>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Payload reference" icon="brackets-curly" href="https://docs.connectly.ai/webhooks/payload-types">
    Every payload shape with full JSON examples — text, media, button replies, referrals, and delivery status.
  </Card>

  <Card title="Create webhook" icon="plus" href="https://docs.connectly.ai/api-reference/create-webhook">
    Register an endpoint for a topic, with filtering and configuration options.
  </Card>

  <Card title="Update webhook" icon="pen" href="https://docs.connectly.ai/api-reference/update-webhook">
    Change the destination URL or configuration of an existing registration.
  </Card>

  <Card title="Delete webhook" icon="trash" href="https://docs.connectly.ai/api-reference/delete-webhook">
    Permanently remove a webhook registration.
  </Card>
</CardGroup>