curl --request POST \
--url https://api.omni.z-api.io/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://destino/webhook",
"description": "Webhook de template",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"signing": false,
"authType": "NONE"
}
'{
"id": "8F2C00000000000000000000000000A1",
"channelId": null,
"instanceId": null,
"url": "https://destino/webhook",
"description": "Webhook de template",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"status": "ENABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-07-15T19:00:00.000+00:00",
"updatedAt": "2026-07-15T19:00:00.000+00:00"
}Criar webhook de template
Registre um webhook de template (independente de instância)
curl --request POST \
--url https://api.omni.z-api.io/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://destino/webhook",
"description": "Webhook de template",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"signing": false,
"authType": "NONE"
}
'{
"id": "8F2C00000000000000000000000000A1",
"channelId": null,
"instanceId": null,
"url": "https://destino/webhook",
"description": "Webhook de template",
"events": [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
],
"status": "ENABLED",
"signing": false,
"secret": null,
"auth": {
"type": "NONE",
"configured": false
},
"payloadFormat": "DEFAULT",
"customAttributes": {},
"createdAt": "2026-07-15T19:00:00.000+00:00",
"updatedAt": "2026-07-15T19:00:00.000+00:00"
}Conceituação
Cria um webhook de template. Ele não depende de uma instância — oinstanceId é gravado como null automaticamente — e recebe apenas os eventos de template do WhatsApp.
O campo events aceita somente UPDATE_TEMPLATE_STATUS e UPDATE_TEMPLATE_CATEGORY. Qualquer evento não-template resulta em 422.
payloadFormat é ignorado
Para webhooks de template o formato é sempre DEFAULT. Você pode omitir o campo; se enviado (qualquer valor), ele é silenciosamente descartado e persistido como DEFAULT.
Assinatura HMAC
Sesigning: true, o campo secret é gerado e retornado apenas nesta resposta. Armazene-o com segurança — ele não será exibido novamente.
Autorizações
Secret Key gerada no painel de Segurança do Omni Z-API
Corpo
URL de destino dos eventos
"https://destino/webhook"
Somente eventos de template. Pelo menos um obrigatório. Qualquer evento não-template resulta em 422.
1Eventos de template aceitos: UPDATE_TEMPLATE_STATUS (atualização de status do template — aprovado/rejeitado etc.) e UPDATE_TEMPLATE_CATEGORY (atualização de categoria do template).
UPDATE_TEMPLATE_STATUS, UPDATE_TEMPLATE_CATEGORY [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
]
Descrição opcional do webhook
"Webhook de template"
Habilita assinatura HMAC-SHA256. Quando true, gera e retorna um secret de 64 caracteres hex apenas na criação/atualização.
false
Tipo de autenticação (forma plana). Alternativa ao objeto auth.
NONE, BEARER, API_KEY, BASIC, CUSTOM_HEADER "NONE"
Credencial para BEARER (forma plana)
Credencial para API_KEY (forma plana)
Forma aninhada da autenticação. Para BASIC use username+password; para CUSTOM_HEADER use headerName+headerValue.
Show child attributes
Show child attributes
Ignorado para webhooks de template — o formato é sempre DEFAULT. Pode ser omitido; se enviado (qualquer valor), é descartado e persistido como DEFAULT.
DEFAULT "DEFAULT"
Mapa livre de atributos extras
{}
Resposta
Webhook de template criado com sucesso. channelId e instanceId vêm null. O campo secret é retornado apenas nesta resposta quando signing é true.
ID único do webhook de template
"8F2C00000000000000000000000000A1"
Sempre null para webhooks de template
null
Descontinuado e sempre null para webhooks de template
null
URL de destino dos eventos
"https://destino/webhook"
Descrição do webhook
"Webhook de template"
Eventos de template configurados
Eventos de template aceitos: UPDATE_TEMPLATE_STATUS (atualização de status do template — aprovado/rejeitado etc.) e UPDATE_TEMPLATE_CATEGORY (atualização de categoria do template).
UPDATE_TEMPLATE_STATUS, UPDATE_TEMPLATE_CATEGORY [
"UPDATE_TEMPLATE_STATUS",
"UPDATE_TEMPLATE_CATEGORY"
]
Status atual do webhook
ENABLED, DISABLED "ENABLED"
Indica se a assinatura HMAC está habilitada
false
Resumo da autenticação configurada — credenciais não são retornadas por segurança
Show child attributes
Show child attributes
Sempre DEFAULT para webhooks de template
DEFAULT "DEFAULT"
{}
"2026-07-15T19:00:00.000+00:00"
"2026-07-15T19:00:00.000+00:00"
Segredo HMAC de 64 caracteres hex — retornado apenas quando signing = true no create/update. null quando a assinatura está desabilitada. Não poderá ser recuperado depois.
null