Pular para o conteúdo principal

​
O que são webhooks?

Webhooks são notificações HTTP que o envia ao seu servidor quando eventos acontecem em um canal — como uma mensagem recebida, status de entrega, ou mudança de conexão. Em vez de o seu sistema consultar a API periodicamente (polling), o envia os eventos para você assim que acontecem. 
Cliente envia mensagem → Hub Message → POST para sua URL → Seu sistema processa
Webhooks exigem a role ENTERPRISE na sua conta. Se sua conta não tem essa role, as chamadas de CRUD de webhook retornam 422. Entre em contato com o suporte para habilitar.

​
Eventos disponíveis

EventoQuando é disparado
MESSAGE_RECEIVEDUma mensagem foi recebida no canal
MESSAGE_DELIVERYConfirmação de entrega de uma mensagem enviada
MESSAGE_STATUSAtualização de status de uma mensagem (lida, falha, etc.)
RECEIVED_STATUSCombinação de recebimento e status
RECEIVED_AND_DELIVERYCombinação de recebimento e entrega
CONNECTEDO canal foi conectado
DISCONNECTEDO canal foi desconectado
PRESENCE_CHATIndicador de presença ou digitação de um contato
INITIAL_DATASincronização inicial de dados ao conectar o canal
BLOCKEvento de bloqueio de contato

​
Formatos de payload

O suporta três formatos de payload:
FormatoDescrição
DEFAULTFormato padrão do Hub Message
Z_APIFormato compatível com a Z-API — ideal para migração ou sistemas já integrados com Z-API

​
Autenticação do webhook

Você pode configurar como o se autentica ao chamar sua URL:
TipoComo funciona
NONESem autenticação (não recomendado em produção)
BEAREREnvia Authorization: Bearer <token>
API_KEYEnvia uma chave de API configurada
BASICHTTP Basic Authentication (username:password)
CUSTOM_HEADEREnvia um header customizado com nome e valor definidos por você

​
Assinatura HMAC

Para garantir que as requisições recebidas são realmente do e não foram adulteradas, habilite a assinatura HMAC configurando signing: true ao criar o webhook. Quando habilitado:
  • Um secret de 64 caracteres hexadecimais é gerado e retornado apenas uma vez na criação/atualização.
  • Cada requisição enviada ao seu webhook inclui um header com a assinatura HMAC-SHA256 calculada sobre o payload.
  • Você verifica a assinatura no seu servidor usando o secret armazenado.
O secret é exibido apenas na resposta do POST /webhooks (criar) ou PATCH /webhooks/{id} (atualizar com signing: true). Armazene-o com segurança — ele não pode ser recuperado depois.

​
Por canal

Cada webhook é associado a um canal específico via channelId. Um mesmo canal pode ter múltiplos webhooks com configurações diferentes — por exemplo, um para mensagens e outro para eventos de conexão.

​
Gerenciamento

Criar webhook

Registre um novo endpoint de webhook em um canal.

Listar webhooks

Veja todos os webhooks de um canal.

Atualizar webhook

Atualize URL, eventos, autenticação ou status.

Deletar webhook

Remova um webhook de um canal.

Estrutura dos payloads

Exemplos reais dos payloads recebidos para cada tipo de mensagem.