curl --request POST \
--url https://api.omni.z-api.io/v1/default-instance-webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos os canais",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
}
'{
"id": "5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B",
"channelId": null,
"instanceId": null,
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos os canais",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
],
"status": "ENABLED",
"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:00:00.000+00:00"
}Criar webhook padrão
Cadastre um webhook que recebe os eventos de todos os canais do workspace
curl --request POST \
--url https://api.omni.z-api.io/v1/default-instance-webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos os canais",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
}
'{
"id": "5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B",
"channelId": null,
"instanceId": null,
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"description": "Eventos de todos os canais",
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
],
"status": "ENABLED",
"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:00:00.000+00:00"
}Conceituação
Cria um webhook padrão no workspace da secret key. A partir da criação, o Omni Z-API envia para a URL informada os eventos assinados de todo canal do workspace que não tem webhook próprio ativo. Veja Quem recebe cada evento. O campoevents aceita só eventos de canal (MESSAGE_RECEIVED, MESSAGE_STATUS, CONNECTED etc.). Evento de template resulta em 422.
Formato
payloadFormat aceita DEFAULT (quando omitido) e Z_API. CHATWOOT resulta em 422: o Chatwoot se configura no webhook de cada canal.
Limite
Cada workspace tem até 5 webhooks padrão, contando os habilitados e os desabilitados. O sexto resulta em422 com Default instance webhook limit reached (5).
Assinatura HMAC
Sesigning: true, o campo secret é gerado e retornado apenas nesta resposta. Armazene-o com segurança: ele não será exibido novamente.
A assinatura chega no header x-webhook-signature e é calculada sobre uma string canônica de cinco campos, não apenas sobre o corpo. Veja Assinatura HMAC.
http ou https, com até 2048 caracteres, e o host precisa resolver só para endereços públicos.Autorizações
Secret Key gerada no painel de Segurança do Omni Z-API
Corpo
Corpo da criação
URL de destino dos eventos. URL absoluta http ou https, com até 2048 caracteres, cujo host resolve só para endereços públicos.
"https://app.suaempresa.com/webhooks/omni-zapi"
Eventos de canal que o webhook recebe. Pelo menos um. O nome é aceito em qualquer caixa.
1MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS",
"DISCONNECTED"
]
Descrição opcional do webhook
"Eventos de todos os canais"
true gera um secret de 64 caracteres hexadecimais para a assinatura HMAC, devolvido só nesta resposta.
Tipo de autenticação (forma plana). Alternativa ao objeto auth.
NONE, BEARER, API_KEY, BASIC, CUSTOM_HEADER Credencial para BEARER (forma plana)
Credencial para API_KEY (forma plana)
Como o Omni Z-API se autentica ao chamar a sua URL
Show child attributes
Show child attributes
DEFAULT (padrão quando omitido) ou Z_API. CHATWOOT é recusado com 422: configure o Chatwoot no webhook do canal. Outro valor é tratado como DEFAULT.
DEFAULT, Z_API Mapa livre de atributos extras
Resposta
Webhook padrão criado. channelId e instanceId vêm null. O secret vem preenchido só quando o pedido traz signing: true, e esta é a única vez em que ele aparece.
ID do webhook padrão
"5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B"
Sempre null: o webhook padrão não pertence a um canal
null
Sempre null. Campo legado, mantido por compatibilidade
null
"https://app.suaempresa.com/webhooks/omni-zapi"
"Eventos de todos os canais"
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK ENABLED ou DISABLED
ENABLED, DISABLED true quando a assinatura HMAC está ligada
Segredo da assinatura HMAC. Vem preenchido só na resposta que o gerou (signing: true); nas demais, null.
Resumo da autenticação configurada. As credenciais não são retornadas.
Show child attributes
Show child attributes
DEFAULT, Z_API Data de criação
Data da última alteração