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

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