curl --request PATCH \
--url https://api.omni.z-api.io/v1/default-instance-webhooks/{webhookId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "DISABLED"
}
'{
"id": "5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B",
"channelId": null,
"instanceId": null,
"url": "https://app.yourcompany.com/webhooks/omni-zapi",
"description": "Events from all channels",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
],
"status": "DISABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-10-22T15:00:00.000+00:00",
"updatedAt": "2026-10-22T15:30:00.000+00:00"
}Update default webhook
Update the configuration of an existing default webhook
curl --request PATCH \
--url https://api.omni.z-api.io/v1/default-instance-webhooks/{webhookId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "DISABLED"
}
'{
"id": "5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B",
"channelId": null,
"instanceId": null,
"url": "https://app.yourcompany.com/webhooks/omni-zapi",
"description": "Events from all channels",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
],
"status": "DISABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-10-22T15:00:00.000+00:00",
"updatedAt": "2026-10-22T15:30:00.000+00:00"
}Overview
Partially updates a default webhook. Only the fields sent in the body are updated; the rest stay as they are.Updating events
When you send theevents field, the list replaces the existing events and must contain only channel events (a template event results in 422). An empty list results in 400: to keep the events, omit the field.
{ "events": ["MESSAGE_RECEIVED", "CONNECTED", "DISCONNECTED"] }
Disabling temporarily
{ "status": "DISABLED" }
{ "status": "ENABLED" }. A disabled webhook still counts toward the workspace limit of 5.
Format
payloadFormat accepts DEFAULT and Z_API. CHATWOOT results in 422.
HMAC signing
signing: true generates a new secret, returned only in this response; signing: false turns signing off. Without signing: true, the response has secret: null and the stored secret does not change.
signing: true generates a new secret every time, even when signing was already on and you only wanted to change another field. To keep the current secret, omit the signing field.http or https, up to 2048 characters, with a host that resolves only to public addresses.Authorizations
Secret Key generated in the Omni Z-API Security panel
Path Parameters
Default webhook ID
"5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B"
Body
All fields are optional: only the fields you send are updated.
New destination URL. Only a URL different from the stored one is checked.
"https://new-url.yourcompany.com/webhooks/omni-zapi"
Optional webhook description
"Events from all channels"
New list of channel events. Replaces the whole list. To keep the events, omit the field.
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
DISABLED pauses the webhook without deleting it; ENABLED enables it again
ENABLED, DISABLED true generates a new secret (returned only in this response), even if signing was already on. false turns signing off. Omit it to keep things as they are.
Authentication type (flat form). Alternative to the auth object.
NONE, BEARER, API_KEY, BASIC, CUSTOM_HEADER Credential for BEARER (flat form)
Credential for API_KEY (flat form)
How Omni Z-API authenticates when calling your URL
Show child attributes
Show child attributes
DEFAULT or Z_API. CHATWOOT is rejected with 422. Omit it to keep the current format.
DEFAULT, Z_API Free map of extra attributes
Response
Default webhook updated. secret is null, except when the request has signing: true.
Default webhook ID
"5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B"
Always null: the default webhook does not belong to a channel
null
Always null. Legacy field, kept for compatibility
null
"https://app.yourcompany.com/webhooks/omni-zapi"
"Events from all channels"
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK ENABLED or DISABLED
ENABLED, DISABLED true when HMAC signing is on
HMAC signing secret. Filled only in the response that generated it (signing: true); null otherwise.
Summary of the configured authentication. Credentials are not returned.
Show child attributes
Show child attributes
DEFAULT, Z_API Creation date
Last update date