Skip to main content
POST

​
Overview

Creates a default webhook in the secret key’s workspace. From then on, Omni Z-API sends to the given URL the subscribed events of every channel in the workspace that has no active webhook of its own. See Who receives each event. The events field accepts only channel events (MESSAGE_RECEIVED, MESSAGE_STATUS, CONNECTED, etc.). A template event results in 422.

​
Format

payloadFormat accepts DEFAULT (when omitted) and Z_API. CHATWOOT results in 422: Chatwoot is configured on each channel’s webhook.

​
Limit

Each workspace has up to 5 default webhooks, counting enabled and disabled ones. The sixth results in 422 with Default instance webhook limit reached (5).

​
HMAC signing

If signing: true, the secret field is generated and returned only in this response. Store it securely: it will not be shown again. The signature arrives in the x-webhook-signature header and is computed over a canonical string of five fields, not just the body. See HMAC signing.
Nothing is saved when the request is rejected. The URL must be absolute, http or https, up to 2048 characters, and its host must resolve only to public addresses.

Authorizations

​
Authorization
string
header
required

Secret Key generated in the Omni Z-API Security panel

Body

application/json

Creation body

​
url
string
required

Destination URL for the events. Absolute http or https URL, up to 2048 characters, whose host resolves only to public addresses.

Example:

"https://app.yourcompany.com/webhooks/omni-zapi"

​
events
enum<string>[]
required

Channel events the webhook receives. At least one. Names are accepted in any case.

Minimum array length: 1
Available options:
MESSAGE_RECEIVED,
MESSAGE_DELIVERY,
MESSAGE_STATUS,
RECEIVED_STATUS,
RECEIVED_AND_DELIVERY,
CONNECTED,
DISCONNECTED,
PRESENCE_CHAT,
INITIAL_DATA,
BLOCK
Example:
​
description
string

Optional webhook description

Example:

"Events from all channels"

​
signing
boolean
default:false

true generates a 64-character hexadecimal secret for HMAC signing, returned only in this response.

​
authType
enum<string>
default:NONE

Authentication type (flat form). Alternative to the auth object.

Available options:
NONE,
BEARER,
API_KEY,
BASIC,
CUSTOM_HEADER
​
token
string

Credential for BEARER (flat form)

​
key
string

Credential for API_KEY (flat form)

​
auth
object

How Omni Z-API authenticates when calling your URL

​
payloadFormat
enum<string>
default:DEFAULT

DEFAULT (used when omitted) or Z_API. CHATWOOT is rejected with 422: configure Chatwoot on the channel webhook. Any other value is treated as DEFAULT.

Available options:
DEFAULT,
Z_API
​
customAttributes
object

Free map of extra attributes

Response

Default webhook created. channelId and instanceId are null. secret is filled only when the request has signing: true, and this is the only time it is shown.

​
id
string

Default webhook ID

Example:

"5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B"

​
channelId
string | null

Always null: the default webhook does not belong to a channel

Example:

null

​
instanceId
string | null
deprecated

Always null. Legacy field, kept for compatibility

Example:

null

​
url
string
Example:

"https://app.yourcompany.com/webhooks/omni-zapi"

​
description
string | null
Example:

"Events from all channels"

​
events
enum<string>[]
Available options:
MESSAGE_RECEIVED,
MESSAGE_DELIVERY,
MESSAGE_STATUS,
RECEIVED_STATUS,
RECEIVED_AND_DELIVERY,
CONNECTED,
DISCONNECTED,
PRESENCE_CHAT,
INITIAL_DATA,
BLOCK
​
status
enum<string>

ENABLED or DISABLED

Available options:
ENABLED,
DISABLED
​
signing
boolean

true when HMAC signing is on

​
secret
string | null

HMAC signing secret. Filled only in the response that generated it (signing: true); null otherwise.

​
auth
object

Summary of the configured authentication. Credentials are not returned.

​
payloadFormat
enum<string>
Available options:
DEFAULT,
Z_API
​
customAttributes
object
​
createdAt
string<date-time>

Creation date

​
updatedAt
string<date-time>

Last update date