Skip to main content
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

TopicDescription
messagesInbound WhatsApp messages sent to your business number by customers.
delivery_statusDelivery status updates for messages you sent: sent, delivered, read, or delivery_failed.
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 rather than deleting and recreating, to avoid a gap in event delivery.

​
Register your endpoint

Before you start receiving events, register your endpoint for the topic you want: 
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 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. 
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))
Reject any request where the computed HMAC does not match the x-connectly-hmac-sha256 header. Never process unauthenticated webhook payloads.

​
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: 
{ "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:
1

sent

The message was dispatched to the recipient. Delivery is not yet confirmed.
2

delivered

The message reached the recipient’s device. It may not have been opened yet.
3

read

The recipient opened the message in their WhatsApp app.
4

delivery_failed

The message could not be delivered. The event includes an error object with a cntTraceId you can share with Connectly support.
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.

​
Next steps

Payload reference

Every payload shape with full JSON examples — text, media, button replies, referrals, and delivery status.

Create webhook

Register an endpoint for a topic, with filtering and configuration options.

Update webhook

Change the destination URL or configuration of an existing registration.

Delete webhook

Permanently remove a webhook registration.