Update webhook

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

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.yourcompany.com/webhooks/omni-zapi",
  "description": "Main production webhook",
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "d4e5f6789012345678901234abcdef0123456789abcdef0123456789ab12c3d4",
  "auth": {
    "type": "BEARER",
    "configured": true
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-20T14:00:00.000+0000"
}

PATCH

channels

{channelId}

webhooks

{webhookId}

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

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.yourcompany.com/webhooks/omni-zapi",
  "description": "Main production webhook",
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "d4e5f6789012345678901234abcdef0123456789abcdef0123456789ab12c3d4",
  "auth": {
    "type": "BEARER",
    "configured": true
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-20T14:00:00.000+0000"
}

Overview

Partially updates a 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 webhook’s events:

{ "events": ["MESSAGE_RECEIVED", "MESSAGE_STATUS", "CONNECTED"] }

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.

Enabling or rotating HMAC signing

If you send signing: true, a new secret is generated and returned in this response. Use this also to rotate the secret without recreating the webhook.

{ "signing": true }

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 with the new secret, see HMAC signing.

Temporarily disabling

{ "status": "DISABLED" }

The webhook stops receiving events while DISABLED. To reactivate:

{ "status": "ENABLED" }

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

The webhookId is obtained from the Create webhook or List webhooks endpoint.

Authorizations

Authorization

string

header

required

Secret Key generated in the Omni Z-API Security panel

Path Parameters

channelId

string

required

Channel ID

Example:

"019E4C54B1B375A28970B605CA9B03C3"

webhookId

string

required

Webhook ID

Example:

"A1B2C3D4E5F6789012345678901234AB"

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/omni-zapi"

description

string

New description

events

enum<string>[]

New event list. Replaces the events the API knows; a stored event the API does not know yet is kept. Cannot be empty (400).

Available options:

MESSAGE_RECEIVED,

MESSAGE_DELIVERY,

MESSAGE_STATUS,

RECEIVED_STATUS,

RECEIVED_AND_DELIVERY,

CONNECTED,

DISCONNECTED,

PRESENCE_CHAT,

INITIAL_DATA,

BLOCK

status

enum<string>

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

Available options:

ENABLED,

DISABLED

signing

boolean

Enables or rotates the HMAC signature. Generates a new secret returned in the response.

auth

object

Configures how Omni Z-API authenticates when calling your URL

Show child attributes

payloadFormat

enum<string>

Available options:

DEFAULT,

Z_API,

CHATWOOT

customAttributes

object

Response

Webhook updated successfully. The secret field is returned only when signing was enabled in this update.

string

Unique webhook ID

Example:

"A1B2C3D4E5F6789012345678901234AB"

channelId

string

ID of the channel this webhook belongs to

Example:

"019E4C54B1B375A28970B605CA9B03C3"

instanceId

string

deprecated

Deprecated — use channelId instead

Example:

"019E4C54B1B375A28970B605CA9B03C3"

url

string

Event destination URL

Example:

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

description

string | null

Webhook description

Example:

"Main production webhook"

events

string[]

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

Example:

["MESSAGE_RECEIVED", "MESSAGE_STATUS"]

status

enum<string>

Current webhook status

Available options:

ENABLED,

DISABLED

Example:

"ENABLED"

signing

boolean

Indicates whether HMAC signing is enabled

Example:

true

auth

object

Summary of configured authentication — credentials are not returned for security

Show child attributes

payloadFormat

enum<string>

Format of the delivered payload

Available options:

DEFAULT,

Z_API,

CHATWOOT

Example:

"DEFAULT"

customAttributes

object

Configured extra attributes

Example:

{}

createdAt

string<date-time>

Creation date

Example:

"2025-01-15T10:30:00.000+0000"

updatedAt

string<date-time>

Last update date

Example:

"2025-01-15T10:30:00.000+0000"

secret

string

64-character hex HMAC secret — returned only when signing is enabled on create or update. Store it securely; it cannot be retrieved later.

Example:

"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"

Channels

Messages

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

Overview

Updating events

Changing the URL

Enabling or rotating HMAC signing

Temporarily disabling

Authorizations

Path Parameters

Body

Response

​Overview

​Updating events

​Changing the URL

​Enabling or rotating HMAC signing

​Temporarily disabling

Authorizations

Path Parameters

Body

Response

Overview

Updating events

Changing the URL

Enabling or rotating HMAC signing

Temporarily disabling