Create template webhook

curl --request POST \
  --url https://api.omni.z-api.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.yourcompany.com/webhooks/templates",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "signing": false,
  "authType": "NONE"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://app.yourcompany.com/webhooks/templates",
  "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"
}

POST

webhooks

curl --request POST \
  --url https://api.omni.z-api.io/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://app.yourcompany.com/webhooks/templates",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "signing": false,
  "authType": "NONE"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://app.yourcompany.com/webhooks/templates",
  "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 — the instanceId 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

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 over the body alone. See HMAC signing.

Validation

The request is refused with 400, and nothing is saved, in these cases:

Case	Response
`url` missing or blank	`{"error": "URL is required"}`
`url` in the wrong format, or with a host that does not resolve only to public addresses	see Webhook URL
`events` missing or empty	`{"error": "At least one event is required"}`
An `events` item that is null, blank, or a name that does not exist	`{"error": "events contains an unknown or empty event name"}`
`auth.type` `CUSTOM_HEADER` without `auth.headerName`	`{"error": "Header name is required for CUSTOM_HEADER auth type"}`
Authentication other than `NONE` without the credential for its type	`{"error": "Credentials are required when auth type is not NONE"}`

Event names are accepted in any letter case. The invalid-name response does not echo the value you sent.

After creation, routing may take up to ~5 min to reflect (cache TTL).

Authorizations

Authorization

string

header

required

Secret Key generated in the Omni Z-API Security panel

Body

application/json

url

string

required

Destination URL for the events: absolute, http or https, up to 2048 characters. The host must exist in DNS and resolve only to public addresses; otherwise, 400.

Example:

"https://app.yourcompany.com/webhooks/templates"

events

enum<string>[]

required

Template events only. At least one required. Any non-template event results in 422; a name that does not exist, null or blank results in 400.

Minimum array length: 1

Accepted template events: UPDATE_TEMPLATE_STATUS (template status update — approved/rejected etc.) and UPDATE_TEMPLATE_CATEGORY (template category update).

Available options:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Example:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

description

string

Optional webhook description

Example:

"Template webhook"

signing

boolean

default:false

Enables HMAC-SHA256 signing. When true, generates and returns a 64-character hex secret only on create/update.

Example:

false

authType

enum<string>

default:NONE

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

Available options:

NONE,

BEARER,

API_KEY,

BASIC,

CUSTOM_HEADER

Example:

"NONE"

token

string

Credential for BEARER (flat form)

key

string

Credential for API_KEY (flat form)

auth

object

Nested authentication form. For BASIC use username+password; for CUSTOM_HEADER use headerName+headerValue.

Show child attributes

payloadFormat

enum<string>

default:DEFAULT

Ignored for template webhooks — the format is always DEFAULT. May be omitted; if sent (any value), it is discarded and persisted as DEFAULT.

Available options:

DEFAULT

Example:

"DEFAULT"

customAttributes

object

Free-form map of extra attributes

Example:

{}

Response

Template webhook created successfully. channelId and instanceId come back null. The secret field is returned only in this response when signing is true.

string

Unique template webhook ID

Example:

"8F2C00000000000000000000000000A1"

channelId

string | null

Always null for template webhooks

Example:

null

instanceId

string | null

deprecated

Deprecated and always null for template webhooks

Example:

null

url

string

Destination URL for the events

Example:

"https://app.yourcompany.com/webhooks/templates"

description

string | null

Webhook description

Example:

"Template webhook"

events

enum<string>[]

Configured template events A stored event the API does not know yet is not listed here.

Accepted template events: UPDATE_TEMPLATE_STATUS (template status update — approved/rejected etc.) and UPDATE_TEMPLATE_CATEGORY (template category update).

Available options:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Example:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

status

enum<string>

Current webhook status

Available options:

ENABLED,

DISABLED

Example:

"ENABLED"

signing

boolean

Indicates whether HMAC signing is enabled

Example:

false

auth

object

Summary of the configured authentication — credentials are not returned for security reasons

Show child attributes

payloadFormat

enum<string>

Always DEFAULT for template webhooks

Available options:

DEFAULT

Example:

"DEFAULT"

customAttributes

object

Example:

{}

createdAt

string<date-time>

Example:

"2026-07-15T19:00:00.000+00:00"

updatedAt

string<date-time>

Example:

"2026-07-15T19:00:00.000+00:00"

secret

string | null

64-character hex HMAC secret — returned only when signing = true on create/update. null when signing is disabled. It cannot be retrieved afterwards.

Example:

null

Channels

Messages

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

Create template webhook

Overview

`payloadFormat` is ignored

HMAC signing

Validation

Authorizations

Body

Response

​Overview

​payloadFormat is ignored

​HMAC signing

​Validation

Authorizations

Body

Response

Overview

`payloadFormat` is ignored

HMAC signing

Validation