curl --request POST \
--url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"events": [
"MESSAGE_RECEIVED"
]
}
'{
"id": "A1B2C3D4E5F6789012345678901234AB",
"channelId": "019E4C54B1B375A28970B605CA9B03C3",
"instanceId": "019E4C54B1B375A28970B605CA9B03C3",
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"description": null,
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS"
],
"status": "ENABLED",
"signing": true,
"secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2025-01-15T10:30:00.000+0000",
"updatedAt": "2025-01-15T10:30:00.000+0000"
}Criar webhook
Registre um endpoint de webhook em um canal
curl --request POST \
--url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"events": [
"MESSAGE_RECEIVED"
]
}
'{
"id": "A1B2C3D4E5F6789012345678901234AB",
"channelId": "019E4C54B1B375A28970B605CA9B03C3",
"instanceId": "019E4C54B1B375A28970B605CA9B03C3",
"url": "https://app.suaempresa.com/webhooks/omni-zapi",
"description": null,
"events": [
"MESSAGE_RECEIVED",
"MESSAGE_STATUS"
],
"status": "ENABLED",
"signing": true,
"secret": "a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab",
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2025-01-15T10:30:00.000+0000",
"updatedAt": "2025-01-15T10:30:00.000+0000"
}Conceituação
Registra um novo endpoint de webhook no canal. A partir da criação, o passa a enviar os eventos configurados para a URL informada. Um canal pode ter múltiplos webhooks — útil para enviar eventos diferentes para sistemas diferentes, ou para manter webhooks com formatos distintos.Assinatura HMAC
Sesigning: true, o campo secret é gerado automaticamente e retornado apenas nesta resposta. Armazene-o com segurança — ele não será exibido novamente em nenhuma outra chamada.
Use o secret para verificar a autenticidade das requisições recebidas no seu servidor. Calcule o HMAC-SHA256 sobre o body recebido usando o secret e compare com o header de assinatura enviado pelo .
channelId é obtido através do endpoint Criar canal.Autorizações
Secret Key gerada no painel de Segurança do Omni Z-API
Parâmetros de caminho
ID do canal
"019E4C54B1B375A28970B605CA9B03C3"
Corpo
URL de destino dos eventos (máx. 2048 caracteres)
"https://app.suaempresa.com/webhooks/omni-zapi"
Tipos de evento a receber. Pelo menos um obrigatório.
MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK ["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
Descrição opcional do webhook
"Webhook principal de produção"
Habilita assinatura HMAC-SHA256. Quando true, um secret de 64 caracteres hex é gerado e retornado apenas na criação/atualização. Use-o para verificar a autenticidade das requisições recebidas.
true
Configura como o Omni Z-API se autentica ao chamar sua URL
Show child attributes
Show child attributes
Formato do payload entregue ao webhook. DEFAULT é o formato do Omni Z-API; Z_API mantém a estrutura da Z-API para quem está migrando; CHATWOOT entrega no formato esperado pelo Chatwoot.
DEFAULT, Z_API, CHATWOOT "DEFAULT"
Atributos extras
{}
Resposta
Webhook criado com sucesso. O campo secret é retornado apenas nesta resposta quando signing é true — armazene-o com segurança.
ID único do webhook
"A1B2C3D4E5F6789012345678901234AB"
ID do canal ao qual o webhook pertence
"019E4C54B1B375A28970B605CA9B03C3"
Descontinuado — use channelId
"019E4C54B1B375A28970B605CA9B03C3"
URL de destino dos eventos
"https://app.suaempresa.com/webhooks/omni-zapi"
Descrição do webhook
"Webhook principal de produção"
Tipos de evento configurados
["MESSAGE_RECEIVED", "MESSAGE_STATUS"]
Status atual do webhook
ENABLED, DISABLED "ENABLED"
Indica se a assinatura HMAC está habilitada
true
Resumo da autenticação configurada — credenciais não são retornadas por segurança
Show child attributes
Show child attributes
Formato do payload entregue
DEFAULT, Z_API, CHATWOOT "DEFAULT"
Atributos extras configurados
{}
Data de criação
"2025-01-15T10:30:00.000+0000"
Data da última atualização
"2025-01-15T10:30:00.000+0000"
Segredo HMAC de 64 caracteres hex — retornado apenas quando signing é habilitado no create ou update. Armazene-o com segurança; não poderá ser recuperado depois.
"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"