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-destination/webhook",
  "status": "DISABLED"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://new-destination/webhook",
  "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"
}

{
  "error": "Validation error"
}

{
  "error": "Webhook not found"
}

{
  "error": "Global webhooks (without instance) accept only template events"
}

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-destination/webhook",
  "status": "DISABLED"
}
'

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://new-destination/webhook",
  "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"
}

{
  "error": "Validation error"
}

{
  "error": "Webhook not found"
}

{
  "error": "Global webhooks (without instance) accept only template events"
}

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"] }

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.

Temporarily disabling

{ "status": "DISABLED" }

To reactivate, send { "status": "ENABLED" }.

`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

Example:

"https://new-destination/webhook"

description

string

New description

events

enum<string>[]

If sent, replaces the event list — template events only (otherwise → 422).

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

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://destination/webhook"

description

string | null

Webhook description

Example:

"Template webhook"

events

enum<string>[]

Configured template events

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

HMAC signing

Temporarily disabling

`payloadFormat` is still ignored

Authorizations

Path Parameters

Body

Response

​Overview

​Updating events

​HMAC signing

​Temporarily disabling

​payloadFormat is still ignored

Authorizations

Path Parameters

Body

Response

Overview

Updating events

HMAC signing

Temporarily disabling

`payloadFormat` is still ignored