curl --request POST \
--url https://api.omni.z-api.io/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://destination/webhook",
"description": "Template webhook",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"signing": false,
"authType": "NONE"
}
'{
"id": "8F2C00000000000000000000000000A1",
"channelId": null,
"instanceId": null,
"url": "https://destination/webhook",
"description": "Template webhook",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"status": "ENABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-07-15T19:00:00.000+00:00",
"updatedAt": "2026-07-15T19:00:00.000+00:00"
}Create template webhook
Register a template webhook (independent of any instance)
curl --request POST \
--url https://api.omni.z-api.io/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://destination/webhook",
"description": "Template webhook",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"signing": false,
"authType": "NONE"
}
'{
"id": "8F2C00000000000000000000000000A1",
"channelId": null,
"instanceId": null,
"url": "https://destination/webhook",
"description": "Template webhook",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"status": "ENABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-07-15T19:00:00.000+00:00",
"updatedAt": "2026-07-15T19:00:00.000+00:00"
}Overview
Creates a template webhook. It does not depend on an instance — theinstanceId is stored as null automatically — and receives only WhatsApp template events.
The events field accepts only UPDATE_TEMPLATE_STATUS and UPDATE_TEMPLATE_CATEGORY. Any non-template event results in 422.
payloadFormat is ignored
For template webhooks the format is always DEFAULT. You may omit the field; if sent (any value), it is silently discarded and persisted as DEFAULT.
HMAC signing
Ifsigning: true, the secret field is generated and returned only in this response. Store it securely — it will not be shown again.
Authorizations
Secret Key generated in the Omni Z-API Security panel
Body
Destination URL for the events
"https://destination/webhook"
Template events only. At least one required. Any non-template event results in 422.
1Accepted template events: UPDATE_TEMPLATE_STATUS (template status update — approved/rejected etc.) and UPDATE_TEMPLATE_CATEGORY (template category update).
UPDATE_TEMPLATE_STATUS, UPDATE_TEMPLATE_CATEGORY [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
]
Optional webhook description
"Template webhook"
Enables HMAC-SHA256 signing. When true, generates and returns a 64-character hex secret only on create/update.
false
Authentication type (flat form). Alternative to the auth object.
NONE, BEARER, API_KEY, BASIC, CUSTOM_HEADER "NONE"
Credential for BEARER (flat form)
Credential for API_KEY (flat form)
Nested authentication form. For BASIC use username+password; for CUSTOM_HEADER use headerName+headerValue.
Show child attributes
Show child attributes
Ignored for template webhooks — the format is always DEFAULT. May be omitted; if sent (any value), it is discarded and persisted as DEFAULT.
DEFAULT "DEFAULT"
Free-form map of extra attributes
{}
Response
Template webhook created successfully. channelId and instanceId come back null. The secret field is returned only in this response when signing is true.
Unique template webhook ID
"8F2C00000000000000000000000000A1"
Always null for template webhooks
null
Deprecated and always null for template webhooks
null
Destination URL for the events
"https://destination/webhook"
Webhook description
"Template webhook"
Configured template events
Accepted template events: UPDATE_TEMPLATE_STATUS (template status update — approved/rejected etc.) and UPDATE_TEMPLATE_CATEGORY (template category update).
UPDATE_TEMPLATE_STATUS, UPDATE_TEMPLATE_CATEGORY [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
]
Current webhook status
ENABLED, DISABLED "ENABLED"
Indicates whether HMAC signing is enabled
false
Summary of the configured authentication — credentials are not returned for security reasons
Show child attributes
Show child attributes
Always DEFAULT for template webhooks
DEFAULT "DEFAULT"
{}
"2026-07-15T19:00:00.000+00:00"
"2026-07-15T19:00:00.000+00:00"
64-character hex HMAC secret — returned only when signing = true on create/update. null when signing is disabled. It cannot be retrieved afterwards.
null