Como usar webhooks do WhatsApp para criar automações em tempo real com o Z-API

Existe um recurso técnico que deixa toda automação mais inteligente e eficiente: são os webhooks do WhatsApp.

Na prática, são os webhooks que permitem que seu sistema saiba, em tempo real, que uma mensagem chegou. Sem eles, sua integração fica cega: não sabe quando o cliente escreveu, não consegue responder automaticamente e não consegue acionar os fluxos que dependem da interação do usuário.

Um webhook é um recurso usado na internet para que uma aplicação se comunique com outra, fornecendo dados em tempo real sempre que um evento acontecer. 

Dessa forma, os dois sistemas realizam trocas de informações sem que nenhuma ação externa precise ser realizada.

Toda vez que o número conectado receber ou gerar uma interação, o Z-API faz uma requisição com o método POST para a URL configurada previamente, com um corpo em JSON específico para cada tipo de evento.

Neste artigo, vamos falar mais sobre como os webhooks do Z-API funcionam, quais estão disponíveis, como configurar cada um e como usá-los para construir automações confiáveis em tempo real.

O que são webhooks do WhatsApp e qual a função nas automações?

Antes de entrar nos detalhes técnicos, vale consolidar o conceito: um webhook é uma URL do seu servidor que o Z-API chama automaticamente sempre que um evento acontece na instância. 

Quando uma mensagem é recebida, quando uma mensagem enviada é entregue, quando a instância desconecta ou quando o status de um chat muda, o Z-API envia um payload HTTP POST para a URL que você configurou com todos os detalhes do evento.

A diferença entre polling e webhook é fundamental para entender por que webhooks são o modelo correto para automações de WhatsApp:

• Polling: é quando seu sistema pergunta periodicamente para a API: “tem alguma mensagem nova?”. A cada 5, 10 ou 30 segundos, uma requisição é feita, a maioria retorna sem novidade, e quando uma mensagem chega, o sistema só descobre na próxima consulta. Isso gera atraso na resposta, consumo desnecessário de recursos e problemas de escala em operações com muitas instâncias.
• Webhook: inverte essa lógica. Seu sistema não precisa perguntar. O Z-API avisa no momento exato em que o evento acontece, sem atraso, sem desperdício de recursos e independente de quantas instâncias estão ativas.

Para automações que precisam responder em tempo real, como atendimento, qualificação de leads e notificações bidirecionais, essa diferença é o que separa uma integração que funciona de uma que frustra.

Um ponto importante da documentação oficial: você não precisa configurar todos os webhooks. Mas quanto mais controle você tiver sobre sua instância, mais vai conseguir extrair recursos e desenvolver negócios com o Z-API. Configure os que fazem sentido para o seu caso de uso e expanda conforme a operação evolui.

Os webhooks disponíveis no Z-API

A documentação do Z-API organiza os webhooks do WhatsApp em quatro tipos principais, cada um com função específica:

Delivery (Ao enviar)

O webhook de delivery é responsável por avisar que sua mensagem foi entregue ao WhatsApp. Importante: isso não significa necessariamente que o contato a recebeu. Para informações de recebimento e leitura, é necessário observar o webhook de status.

O endpoint para configurar esse webhook é:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-delivery

O payload de retorno desse webhook inclui os seguintes campos:

• phone: número de telefone de destino da mensagem
• zaapId: identificador da mensagem na conversa
• messageId: identificador da mensagem no WhatsApp
• instanceId: identificador da instância
• momment: timestamp em milissegundos do momento em que o evento foi disparado
• type: tipo do evento, nesse caso DeliveryCallback
• error: presente apenas em casos de erro, contém a descrição do problema ocorrido no envio

Um exemplo de retorno de sucesso:

json

{

  “phone”: “554499999999”,

  “zaapId”: “A20DA9C0183A2D35A260F53F5D2B9244”,

  “messageId”: “A20DA9C0183A2D35A260F53F5D2B9244”,

  “instanceId”: “instance.id”,

  “momment”: 1777494009341,

  “type”: “DeliveryCallback”

}

Esse webhook é especialmente útil para sistemas que precisam confirmar que a mensagem chegou ao WhatsApp antes de acionar o próximo passo do fluxo, como uma atualização de status no CRM ou o disparo de uma etapa subsequente na automação.

Para ver todos os exemplos de retorno por situação, incluindo cenários de erro, consulte a página de exemplos de retorno de Ao enviar na documentação oficial.

Receive (Ao receber)

Este é o webhook mais usado em automações. Ele é chamado toda vez que alguém interage com o número conectado no WhatsApp, ou seja, toda vez que uma mensagem chega.

O endpoint para configurar esse webhook é:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-received

Um detalhe importante da documentação: esse webhook também é executado quando a instância está configurada para notificar mensagens enviadas pelo próprio número, o que veremos na seção sobre o webhook update-notify-sent-by-me.

Outro ponto relevante para quem trabalha com mídias: os arquivos de mídia, como imagens, documentos e áudios, ficam disponíveis por 30 dias no armazenamento do Z-API. 

Após esse prazo, os arquivos são removidos. Isso precisa ser considerado em arquiteturas que dependem de processamento posterior de mídias.

O webhook de recebimento suporta todos os tipos de mensagem do WhatsApp. 

Para ver os exemplos de payload por tipo de mensagem, incluindo texto, imagem, áudio, documento, localização, contato, enquete e botões, consulte a página de exemplos de retorno de Ao receber na documentação oficial.

Status

O webhook de status avisa sobre todas as mudanças de status que uma mensagem sofre: se foi recebida, lida, respondida ou excluída.

Um ponto importante da documentação: uma mesma mensagem pode passar por vários status e até ter o mesmo status mais de uma vez, como é o caso de “respondida”. 

Isso significa que seu sistema precisa estar preparado para receber múltiplos eventos de status para a mesma mensagem e tratá-los de acordo com a lógica de negócio correta.

Esse webhook é fundamental para sistemas que precisam saber se o cliente leu a mensagem antes de acionar o próximo passo, como um follow-up automático apenas para quem não leu, ou uma atualização de status no CRM quando a mensagem é confirmada como lida.

Disconnected (Ao desconectar)

Esse webhook é chamado sempre que o Z-API identifica alguma indisponibilidade na comunicação, seja do celular com o WhatsApp ou da conexão entre o celular e o Z-API.

Para operações em produção, monitorar eventos de desconexão é essencial, já que uma instância desconectada sem detecção significa que mensagens chegam mas não são processadas, e a operação para sem que ninguém perceba. 

Com o webhook de desconexão configurado, seu sistema recebe o alerta imediatamente e pode acionar o processo de reconexão automaticamente.

Webhook de mensagens enviadas no WhatsApp: aproveite e veja como isso melhora a operação na prática.

Como configurar os webhooks no Z-API?

A documentação do Z-API oferece dois caminhos para configurar webhooks:

Via painel

Acesse o painel admin, em Instâncias clique no ícone de visualização da instância desejada e nos três pontos escolha “editar“. O campo de webhook aparece na tela de edição da instância.

Via API

Cada webhook tem seu próprio endpoint de configuração via PUT. Você passa a URL do seu sistema no campo value do body da requisição.

Um ponto crítico da documentação: o Z-API não aceita webhooks que não sejam HTTPS. Antes de configurar qualquer webhook, certifique-se de que a URL do seu endpoint tem certificado SSL válido. 

Em desenvolvimento local, ferramentas como ngrok permitem criar um túnel HTTPS temporário para testes.

Atualizar todos os webhooks de uma vez

Para quem quer apontar todos os webhooks para a mesma URL de forma simples, o Z-API oferece um endpoint específico:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-all-webhooks

O body aceita dois campos:

json

{

  “value”: “https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/webhook”,

  “notifySentByMe”: true

}

O campo value define a URL para todos os webhooks. O campo notifySentByMe é opcional e habilita notificações de webhook para mensagens recebidas e enviadas pelo próprio número, o que é detalhado na próxima seção.

Esse endpoint é especialmente útil no momento de setup inicial ou quando você precisa migrar todos os webhooks para uma nova URL sem precisar chamar cada endpoint individualmente.

A funcionalidade notifySentByMe: o que é e quando usar

Essa é uma configuração que merece atenção especial porque muda o comportamento padrão do webhook de recebimento.

Por padrão, o webhook Ao receber notifica apenas mensagens enviadas por outros para o seu número. Com a funcionalidade notifySentByMe habilitada, ele passa a notificar também as mensagens enviadas pelo próprio número conectado.

O endpoint para configurar isso individualmente é:

PUT https://api.z-api.io/instances/{id}/token/{token}/update-notify-sent-by-me

Com o body:

json

{

  “notifySentByMe”: true

}

Um aviso importante da documentação: para que essa funcionalidade opere corretamente, é necessário ter um webhook configurado para o evento Ao receber. Sem isso, não há onde as notificações serão entregues.

Quando essa funcionalidade faz sentido?

Em sistemas de atendimento multiagente, onde diferentes atendentes enviam mensagens pelo mesmo número, habilitar notifySentByMe permite que o sistema registre todas as mensagens enviadas, independente de quem enviou. 

Isso garante que o histórico de conversas no CRM seja completo, incluindo as mensagens que partiram da empresa para o cliente.

Em arquiteturas de auditoria, onde é necessário registrar toda a comunicação que passou pelo número, essa funcionalidade garante que nenhuma mensagem fique de fora do log.

Em sistemas de sincronização entre múltiplos dispositivos, o notifySentByMe permite que o sistema saiba o que foi enviado em cada sessão e mantenha o estado consistente.

Aproveite e confira também: o que é LID no WhatsApp, como funciona e o que muda nas integrações com a API do Z-API.

Como configurar o webhook de recebimento: passo a passo

Aqui está o fluxo completo para colocar o webhook de recebimento funcionando em produção:

1. Criar o endpoint no seu sistema

Seu servidor precisa expor uma URL HTTPS que aceite requisições POST. Esse endpoint recebe os payloads do Z-API e precisa responder com status 200 para confirmar o recebimento.

2. Configurar a URL no Z-API

Faça uma requisição PUT para o endpoint de configuração com a URL do seu sistema:

PUT https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-received

Body:

{

  “value”: “https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/receive”

}

3. Processar o payload recebido

Quando uma mensagem chega no número conectado, o Z-API faz um POST para a URL configurada com o payload da mensagem. Seu sistema extrai os campos relevantes, processa a mensagem e executa a lógica de negócio correspondente.

4. Habilitar notifySentByMe se necessário

Se o seu caso de uso exige receber notificações também das mensagens enviadas pelo número, configure:

PUT https://api.z-api.io/instances/{id}/token/{token}/update-notify-sent-by-me

Body:

{

  “notifySentByMe”: true

}

Casos de uso onde webhooks fazem toda a diferença

Com os webhooks do WhatsApp configurados corretamente, esses são os casos de uso que se tornam possíveis em produção:

Atendimento em tempo real com agente de IA

O webhook de recebimento é o gatilho de toda automação inteligente no WhatsApp. Quando a mensagem chega, o payload é enviado ao sistema, o LLM processa o conteúdo e a resposta é enviada de volta via Z-API. 

Sem o webhook de recebimento funcionando de forma confiável, o agente não consegue operar em tempo real.

Confirmação de entrega e leitura no CRM

O webhook de delivery confirma que a mensagem chegou ao WhatsApp. O webhook de status confirma quando foi recebida e lida pelo destinatário. Com esses dois eventos sendo processados, o CRM pode ser atualizado automaticamente com o status real de cada comunicação, sem nenhuma intervenção manual.

Detecção e recuperação automática de desconexão

O webhook de desconexão permite que o sistema identifique imediatamente quando uma instância perde a conexão e acione o processo de reconexão automaticamente, minimizando o tempo de inatividade da operação.

Histórico completo de conversas

Com notifySentByMe habilitado, o sistema registra tanto as mensagens recebidas quanto as enviadas, construindo um histórico completo de cada conversa que pode ser consultado por qualquer atendente no CRM.

Automações bidirecionais

Uma notificação é enviada ao cliente via Z-API. Quando o cliente responde, o webhook de recebimento entrega essa resposta ao sistema. O sistema processa e aciona a próxima etapa do fluxo automaticamente. O ciclo completo acontece sem nenhuma intervenção humana.

Boas práticas para garantir confiabilidade em produção

A configuração dos webhooks é o primeiro passo. Garantir que funcionem de forma confiável em produção exige algumas práticas adicionais:

Responder 200 rapidamente

O endpoint precisa responder com status 200 imediatamente ao receber o payload. Se o processamento for demorado, delegue para uma fila assíncrona e responda 200 antes de processar. Se o endpoint demorar demais para responder, o Z-API pode interpretar como falha.

Tratar duplicatas com idempotência

Em casos de instabilidade de rede, o Z-API pode reenviar o mesmo evento. Use o identificador único da mensagem presente no payload para verificar se o evento já foi processado antes de executar qualquer ação. Processar a mesma mensagem duas vezes pode gerar respostas duplicadas ao cliente.

Usar HTTPS obrigatoriamente

A documentação é clara: o Z-API não aceita webhooks que não sejam HTTPS. Certifique-se de que o endpoint tem certificado SSL válido antes de configurar qualquer webhook.

Monitorar a saúde dos endpoints

Configurar alertas para quando os webhooks pararem de receber eventos é fundamental para detectar falhas de configuração ou problemas de infraestrutura antes que afetem a operação.

Não compartilhar ID e token

A documentação do Z-API reforça: nunca compartilhe o ID e o token da instância com ninguém. Esses dados dão acesso completo à instância e precisam ser tratados como credenciais sensíveis.

Recursos da documentação para aprofundar

Para quem quer ir além do básico, a documentação oficial do Z-API tem recursos complementares que cobrem casos mais avançados:

A página de exemplos de retorno de Ao enviar detalha todos os cenários possíveis no webhook de delivery, incluindo os diferentes tipos de erro que podem aparecer no campo error do payload.

A página de exemplos de retorno de Ao receber tem exemplos de payload para cada tipo de mensagem suportada: texto, imagem, áudio, vídeo, documento, localização, contato, enquete, botões e mais.

A introdução aos webhooks tem o overview completo de todos os tipos disponíveis e as instruções de configuração via painel e via API.

O endpoint de atualizar todos os webhooks é útil especialmente em setup inicial ou migrações, quando é necessário apontar todos os webhooks para uma nova URL de uma vez.

Conclusão

Os webhooks do WhatsApp são a fundação técnica de qualquer automação que precisa operar em tempo real. 

O Z-API oferece um conjunto completo de webhooks que cobre todos os eventos relevantes de uma operação: recebimento de mensagens, confirmação de entrega, mudanças de status, desconexão da instância e mensagens enviadas pelo próprio número.

Configurar corretamente, usar HTTPS, responder 200 rapidamente, tratar duplicatas e monitorar a saúde dos endpoints são as práticas que transformam um webhook funcional em uma infraestrutura confiável de longo prazo.

Para quem está construindo automações com o Z-API, a documentação oficial tem tudo que é necessário para implementar cada webhook com precisão, desde os endpoints de configuração até os exemplos completos de payload por tipo de evento.

Acesse a documentação de webhooks do Z-API e teste na prática. 👉 Crie sua conta grátis 📄 Documentação de webhooks