What are webhooks?
Webhooks are HTTP notifications that sends to your server when events happen on a channel — such as a message received, delivery status, or connection change. Instead of your system periodically polling the API, pushes events to you as they happen.Webhooks require the ENTERPRISE role on your account. If your account does not have this role, webhook CRUD calls return
422. Contact support to enable it.Available events
| Event | When it is triggered |
|---|---|
MESSAGE_RECEIVED | A message was received on the channel |
MESSAGE_DELIVERY | Delivery confirmation for a sent message |
MESSAGE_STATUS | Message status update (read, failed, etc.) |
RECEIVED_STATUS | Combined received and status |
RECEIVED_AND_DELIVERY | Combined received and delivery |
CONNECTED | The channel was connected |
DISCONNECTED | The channel was disconnected |
PRESENCE_CHAT | Contact presence or typing indicator |
INITIAL_DATA | Initial data sync when channel connects |
BLOCK | Contact block event |
Payload formats
supports three payload formats:| Format | Description |
|---|---|
DEFAULT | Standard Hub Message format |
Z_API | Z-API compatible format — ideal for migration or systems already integrated with Z-API |
Webhook authentication
You can configure how authenticates when calling your URL:| Type | How it works |
|---|---|
NONE | No authentication (not recommended in production) |
BEARER | Sends Authorization: Bearer <token> |
API_KEY | Sends a configured API key |
BASIC | HTTP Basic Authentication (username:password) |
CUSTOM_HEADER | Sends a custom header with a name and value you define |
HMAC signing
To ensure requests received are genuinely from and have not been tampered with, enable HMAC signing by settingsigning: true when creating the webhook.
When enabled:
- A 64-character hexadecimal
secretis generated and returned only once on create/update. - Each request sent to your webhook includes a header with an HMAC-SHA256 signature computed over the payload.
- You verify the signature on your server using the stored
secret.
Per channel
Each webhook is associated with a specific channel viachannelId. A single channel can have multiple webhooks with different configurations — for example, one for messages and another for connection events.
Management
Create webhook
Register a new webhook endpoint on a channel.
List webhooks
View all webhooks for a channel.
Update webhook
Update URL, events, authentication, or status.
Delete webhook
Remove a webhook from a channel.
Payload structure
Real payload examples received for each message type.