Update template webhook

curl --request PATCH \
  --url https://api.omni.z-api.io/v1/webhooks/{webhookId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://new-url.yourcompany.com/webhooks/templates",
  "status": "DISABLED"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://new-url.yourcompany.com/webhooks/templates",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "status": "DISABLED",
  "signing": false,
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2026-07-15T19:00:00.000+00:00",
  "updatedAt": "2026-07-15T19:30:00.000+00:00"
}

PATCH

webhooks

{webhookId}

curl --request PATCH \
  --url https://api.omni.z-api.io/v1/webhooks/{webhookId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://new-url.yourcompany.com/webhooks/templates",
  "status": "DISABLED"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://new-url.yourcompany.com/webhooks/templates",
  "description": "Template webhook",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "status": "DISABLED",
  "signing": false,
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2026-07-15T19:00:00.000+00:00",
  "updatedAt": "2026-07-15T19:30:00.000+00:00"
}

Overview

Partially updates a template webhook’s configuration. Only the fields sent in the body are updated — the rest remain unchanged.

Updating events

When sending the events field, the list replaces the existing events and must contain only template events (otherwise → 422):

{ "events": ["UPDATE_TEMPLATE_STATUS", "UPDATE_TEMPLATE_CATEGORY"] }

The list cannot be empty: "events": [] returns 400 with {"error": "Events cannot be empty when provided"}. To keep the events, omit the field.
An item that is null, blank, or a name that does not exist returns 400 with {"error": "events contains an unknown or empty event name"}, and nothing is changed.

Event the API does not know yet. A webhook may have a stored event that this version of the API does not know yet, for example a new event subscribed from the dashboard before it reached the API. That event does not appear in events in the responses, and it is kept when you replace the events: the PATCH replaces only the events the API knows. A webhook that only has events like that appears with events: [].

Changing the URL

The new url follows the same rules as on creation (see Webhook URL). It is only checked when it changes: a PATCH without url, or with the URL already stored, is not refused because of it.

HMAC signing

signing: true generates a new secret (returned only in this response); signing: false removes signing.

The new secret is returned only in this response. Store it before closing the session.

signing: true rotates the secret every time, including when signing was already enabled and you only meant to change another field in the same request. To avoid rotating, omit the signing field.

To verify the signature, see HMAC signing.

Temporarily disabling

{ "status": "DISABLED" }

To reactivate, send { "status": "ENABLED" }. A status other than ENABLED or DISABLED returns 400 with {"error": "status must be one of [ENABLED, DISABLED]"}.

`payloadFormat` is still ignored

For template webhooks the format is always DEFAULT, even if sent in the update.

After the change, 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

Path Parameters

webhookId

string

required

Template webhook ID

Example:

"8F2C00000000000000000000000000A1"

Body

application/json

All fields are optional — only the fields sent are updated.

url

string

New destination URL, under the same rules as on creation. It is only checked when it changes.

Example:

"https://new-url.yourcompany.com/webhooks/templates"

description

string

New description

events

enum<string>[]

If sent, replaces the events the API knows — template events only (otherwise → 422). A stored event the API does not know yet is kept. Cannot be empty (400).

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

status

enum<string>

DISABLED pauses event delivery without deleting the webhook Any other value returns 400.

Available options:

ENABLED,

DISABLED

signing

boolean

true generates a new secret; false removes signing

authType

enum<string>

NONE clears authentication; the others reconfigure it

Available options:

NONE,

BEARER,

API_KEY,

BASIC,

CUSTOM_HEADER

token

string

Credential for BEARER

key

string

Credential for API_KEY

auth

object

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

Show child attributes

payloadFormat

enum<string>

Ignored for template webhooks

Available options:

DEFAULT

customAttributes

object

Response

Template webhook updated. The secret field is returned only when signing = true in this update.

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

Update template webhook

Overview

Updating events

Changing the URL

HMAC signing

Temporarily disabling

`payloadFormat` is still ignored

Authorizations

Path Parameters

Body

Response

​Overview

​Updating events

​Changing the URL

​HMAC signing

​Temporarily disabling

​payloadFormat is still ignored

Authorizations

Path Parameters

Body

Response

Overview

Updating events

Changing the URL

HMAC signing

Temporarily disabling

`payloadFormat` is still ignored