curl --request POST \
--url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.yourcompany.com/webhooks/omni-zapi",
"events": [
"MESSAGE_RECEIVED"
]
}
'{
"id": "A1B2C3D4E5F6789012345678901234AB",
"channelId": "019E4C54B1B375A28970B605CA9B03C3",
"instanceId": "019E4C54B1B375A28970B605CA9B03C3",
"url": "https://app.yourcompany.com/webhooks/omni-zapi",
"description": null,
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS"
],
"status": "ENABLED",
"signing": true,
"secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2025-01-15T10:30:00.000+0000",
"updatedAt": "2025-01-15T10:30:00.000+0000"
}Create webhook
Register a webhook endpoint on a channel
curl --request POST \
--url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.yourcompany.com/webhooks/omni-zapi",
"events": [
"MESSAGE_RECEIVED"
]
}
'{
"id": "A1B2C3D4E5F6789012345678901234AB",
"channelId": "019E4C54B1B375A28970B605CA9B03C3",
"instanceId": "019E4C54B1B375A28970B605CA9B03C3",
"url": "https://app.yourcompany.com/webhooks/omni-zapi",
"description": null,
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS"
],
"status": "ENABLED",
"signing": true,
"secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2025-01-15T10:30:00.000+0000",
"updatedAt": "2025-01-15T10:30:00.000+0000"
}Overview
Registers a new webhook endpoint on the channel. From creation onwards, starts sending the configured events to the provided URL. A channel can have multiple webhooks — useful for sending different events to different systems, or for maintaining webhooks with different formats.HMAC signing
Ifsigning: true, a secret is automatically generated and returned only in this response. Store it securely — it will not be shown again in any other call.
Use the secret to verify the authenticity of requests received on your server. Compute HMAC-SHA256 over the received body using the secret and compare it with the signing header sent by .
channelId is obtained from the Create channel endpoint.Authorizations
Secret Key generated in the Omni Z-API Security panel
Path Parameters
Channel ID
"019E4C54B1B375A28970B605CA9B03C3"
Body
Event destination URL (max. 2048 characters)
"https://app.yourcompany.com/webhooks/omni-zapi"
Event types to receive. At least one required.
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK ["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
Optional webhook description
"Main production webhook"
Enables HMAC-SHA256 signing. When true, a 64-character hex secret is generated and returned only on create/update. Use it to verify the authenticity of incoming requests.
true
Configures how Omni Z-API authenticates when calling your URL
Show child attributes
Show child attributes
Format of the payload delivered to the webhook. DEFAULT is the Omni Z-API format; Z_API keeps the Z-API structure for those migrating; CHATWOOT delivers in the format Chatwoot expects.
DEFAULT, Z_API, CHATWOOT "DEFAULT"
Extra attributes
{}
Response
Webhook created successfully. The secret field is returned only in this response when signing is true — store it securely.
Unique webhook ID
"A1B2C3D4E5F6789012345678901234AB"
ID of the channel this webhook belongs to
"019E4C54B1B375A28970B605CA9B03C3"
Deprecated — use channelId instead
"019E4C54B1B375A28970B605CA9B03C3"
Event destination URL
"https://app.yourcompany.com/webhooks/omni-zapi"
Webhook description
"Main production webhook"
Configured event types
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
Current webhook status
ENABLED, DISABLED "ENABLED"
Indicates whether HMAC signing is enabled
true
Summary of configured authentication — credentials are not returned for security
Show child attributes
Show child attributes
Format of the delivered payload
DEFAULT, Z_API, CHATWOOT "DEFAULT"
Configured extra attributes
{}
Creation date
"2025-01-15T10:30:00.000+0000"
Last update date
"2025-01-15T10:30:00.000+0000"
64-character hex HMAC secret — returned only when signing is enabled on create or update. Store it securely; it cannot be retrieved later.
"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"