Qual solução de webhooks escolher para monitoramento em tempo real?

Depois da requisição, a empresa precisa saber se o envio foi processado, se chegou ao smartphone, se foi recebido, se foi lido, se houve resposta ou se a conexão apresentou algum problema.

Sem esse acompanhamento, o sistema trabalha às cegas: o CRM pode registrar uma notificação como enviada quando ela falhou; um atendimento pode não identificar uma nova resposta; uma instância pode permanecer desconectada por horas sem que a equipe perceba.

É para acompanhar esses eventos que existem os webhooks, permitindo que a plataforma de comunicação envie informações para o sistema da empresa sempre que determinados eventos acontecem.

No Z-API, os webhooks são requisições POST enviadas para uma URL previamente configurada. A plataforma disponibiliza eventos relacionados a envio, recebimento, status de mensagens e desconexão.

Mas qual solução escolher? Depende do estágio da operação.

Um MVP pode utilizar n8n, Make ou Zapier. Uma operação pequena pode direcionar os eventos para um endpoint próprio. À medida que o volume e a criticidade aumentam, pode fazer sentido adicionar filas, workers, idempotência, DLQ, métricas e alertas.

O ponto principal é avaliar a arquitetura completa de monitoramento, e não apenas se a ferramenta oferece um campo chamado “webhook”.

Neste artigo, você vai entender:

• O que precisa ser monitorado em tempo real;
• Quais eventos são importantes em uma operação de mensageria;
• como diferenciar processamento, entrega, recebimento e leitura;
• Quais arquiteturas de monitoramento existem;
• Como avaliar confiabilidade e segurança;
• Como criar observabilidade e alertas;
• Como configurar webhooks do Z-API;
• Qual arquitetura faz sentido para cada estágio da operação.

O que monitorar em tempo real?

Um monitoramento eficiente acompanha tanto a jornada da mensagem quanto o estado da conexão.

Mensagens enviadas

Quando a empresa solicita um envio, registre pelo menos:

• destinatário;
• tipo de conteúdo;
• origem da solicitação;
• horário;
• identificador retornado pela API.

Esses dados representam a intenção de envio. Eles não comprovam, sozinhos, que a mensagem foi processada ou entregue.

Processamento do envio

O sistema precisa identificar se a instância conseguiu processar a solicitação. Uma falha pode estar relacionada a credenciais, instância desconectada, payload incorreto, destinatário inválido ou outro problema operacional.

Entrega ao app de mensgens

O webhook de Delivery do Z-API informa quando a mensagem foi entregue ao aplicativo de mensagens. 

Esse evento não garante que o contato recebeu o conteúdo. Essa diferença precisa existir no modelo de dados:

entregue ao app ≠ recebido pelo destinatário

Recebimento pelo contato

O status de recebimento representa uma etapa posterior da jornada. Ele permite acompanhar quando a mensagem chega ao contato, de acordo com o evento disponibilizado pela plataforma.

Leitura

A leitura indica que a mensagem foi aberta quando esse status estiver disponível. A ausência de leitura não deve ser tratada automaticamente como falha. O contato pode ter recebido a mensagem e ainda não ter aberto a conversa.

Respostas

Mensagens recebidas dos usuários também são eventos importantes. Uma resposta pode:

• iniciar um atendimento;
• alterar o estágio de um lead;
• atualizar um ticket;
• interromper uma campanha;
• iniciar uma automação;
• gerar uma nova tarefa.

O webhook de Receive é acionado quando alguém interage com o número da empresa.

Desconexões

Uma instância desconectada pode interromper envios, recebimentos e automações. O webhook de Disconnected informa indisponibilidade na comunicação entre telefone, app de mensagens e Z-API.

Esse evento deve gerar um alerta operacional e, quando necessário, iniciar um processo de recuperação.

Tipos de eventos de webhook do Z-API

Os principais eventos podem ser organizados assim:

Evento	O que sinaliza	Ação recomendada
Delivery	Processamento da mensagem para envio ao app ou falha no envio	Atualizar status técnico e investigar erros
Receive	Alguém interagiu com o número	Iniciar atendimento ou automação
Status	Mudança como recebimento, leitura, resposta ou exclusão	Atualizar jornada e métricas
Disconnected	Indisponibilidade da comunicação	Alertar equipe e iniciar recuperação

O evento recebido deve ser registrado antes de iniciar ações externas sempre que a criticidade da operação justificar.

Assim, se uma chamada ao CRM falhar, por exemplo, o evento original continua disponível para reprocessamento.

Webhook de Delivery

O Z-API disponibiliza um endpoint para atualizar a URL do webhook de delivery:

PUT /instances/{instanceId}/token/{token}/update-webhook-delivery

Exemplo:

curl –request PUT \   –url https://api.z-api.io/instances/{instanceId}/token/{token}/update-webhook-delivery \   –header ‘Client-Token: <api-key>’ \   –header ‘Content-Type: application/json’ \   –data ‘{     “value”: “https://seu-dominio.com/webhooks/zapi/delivery”   }

A URL do webhook deve utilizar HTTPS. A resposta documentada para a atualização é:

{   “value”: true }

O callback de delivery pode conter informações como:

• phone;
• zaapId;
• messageId;
• instanceId;
• momment;
• type;
• error, quando houver falha.

O messageId é especialmente importante para relacionar o evento ao envio original.

Webhook de Receive

O webhook de Receive é utilizado quando alguém interage com o número. O evento pode iniciar um fluxo que:

1. identifica o contato;
2. localiza a conversa;
3. verifica se existe atendimento aberto;
4. interrompe uma campanha ativa, quando aplicável;
5. consulta pedido ou cadastro;
6. responde automaticamente;
7. encaminha para um atendente.

A etapa de processamento deve ser separada da recepção do webhook quando houver operações demoradas.

Webhook de Status

O webhook de Status acompanha mudanças na mensagem.

Entre os estados documentados estão:

• received;
• read;
• replied;
• deleted.

Esses eventos permitem atualizar a jornada sem depender de estimativas baseadas em tempo.

Uma mensagem que ainda não foi lida, por exemplo, não deve ser automaticamente reenviada apenas porque determinado período passou. Isso pode criar duplicidade e prejudicar a experiência.

Webhook de Disconnected

A desconexão deve ser tratada como um incidente operacional. O alerta precisa informar:

• qual instância foi afetada;
• quando a indisponibilidade começou;
• há quanto tempo permanece desconectada;
• quais fluxos dependem daquela instância;
• qual procedimento deve ser executado.

Evite tentativas de reconexão infinitas. Registre as tentativas, utilize limites e encaminhe o caso para a equipe responsável quando a indisponibilidade persistir.

Aproveite e conheça plataformas para automatizar fluxos de trabalho com webhooks.

O que uma solução de webhook precisa oferecer?

“Tempo real” não significa que todos os eventos serão instantâneos ou que nenhum evento poderá falhar.

Uma solução confiável precisa estar preparada para atrasos, indisponibilidade, duplicidade e reprocessamento.

Resposta rápida do endpoint

O receptor deve validar o evento, registrar os dados necessários e responder rapidamente. Processamentos demorados dentro da própria requisição aumentam o risco de timeout e duplicidade.

Uma arquitetura mais segura é:

Webhook do Z-API         ↓ Autenticação e validação         ↓ Registro durável do evento         ↓ Resposta HTTP rápida         ↓ Fila de processamento         ↓ CRM, ERP, IA ou atendimento

A regra é simples: receba primeiro, processe depois, quando o fluxo exigir operações demoradas.

Idempotência

O mesmo evento pode ser recebido mais de uma vez. Por isso, crie uma chave de idempotência utilizando os identificadores disponíveis, como:

instanceId + messageId + eventType

Antes de criar um ticket, enviar uma resposta ou atualizar um pedido, verifique se aquele evento já foi processado.

Retentativas

Nem toda falha é permanente. Uma falha temporária pode ser retentada com:

• limite de tentativas;
• intervalo crescente;
• backoff;
• jitter.

Falhas permanentes devem ser encaminhadas para análise, e não permanecer em um loop infinito.

Ordenação

Eventos podem chegar em uma ordem diferente daquela em que ocorreram. O sistema precisa evitar que um status antigo substitua um estado mais recente.  Para isso, utilize timestamps e regras de transição de estado.

Fila durável

Uma fila apenas em memória pode perder eventos durante um reinício.Para processos críticos, como atendimento, pedidos, pagamentos e notificações, prefira uma fila persistente ou uma tabela de eventos com controle de processamento.

Dead-letter queue

Eventos que continuam falhando depois das tentativas previstas devem ser enviados para uma Dead-Letter Queue (DLQ).

Isso permite que a equipe:

1. identifique o erro;
2. corrija a causa;
3. reprocese o evento;
4. mantenha o histórico da falha.

Comparação entre abordagens de monitoramento

Não existe uma única arquitetura correta. A melhor escolha depende do volume, da criticidade e da capacidade técnica da equipe.

1. Polling

No polling, a aplicação consulta periodicamente o provedor para verificar se existem novidades.

Vantagens

• implementação inicial simples;
• útil quando o serviço não oferece webhooks;
• controle sobre o intervalo de consulta.

Limitações

• existe atraso entre o evento e sua descoberta;
• consultas podem ser desnecessárias;
• o controle de cursores aumenta a complexidade;
• eventos podem ser mais difíceis de recuperar;
• desconexões podem demorar para ser identificadas.

O polling pode funcionar como fallback, mas não é a primeira escolha quando a operação depende de reação em tempo real.

2. Webhook direto para a aplicação

Nesse modelo, o Z-API envia os eventos diretamente para um endpoint criado pela empresa.

Vantagens

• baixa latência;
• arquitetura simples;
• controle sobre banco e processamento;
• integração direta com sistemas internos.

Limitações

• a empresa precisa manter o endpoint;
• HTTPS e segurança ficam sob responsabilidade do time;
• fila, idempotência e observabilidade precisam ser implementadas.

É uma boa opção para startups, software houses e equipes com capacidade técnica para operar a integração.

3. Webhook para n8n

O n8n pode receber o evento, iniciar um workflow e conectar o Z-API a CRM, banco de dados, planilhas, IA ou ferramentas de atendimento.

O Webhook node funciona como gatilho para iniciar workflows a partir de eventos externos e possui URLs distintas para teste e produção.

Vantagens

• implementação rápida;
• fluxo visual;
• facilidade para conectar diferentes serviços;
• suporte a requisições HTTP e transformações;
• possibilidade de controlar a infraestrutura em ambientes self-hosted.

Limitações

• workflows mal configurados podem falhar;
• processamento pesado pode atrasar a resposta;
• volume e concorrência precisam ser dimensionados;
• observabilidade depende da configuração do ambiente.

Uma boa prática é separar a recepção do evento do processamento pesado. O endpoint deve responder rapidamente e deixar o restante para uma etapa assíncrona quando necessário.

4. Webhook para Make ou Zapier

Plataformas de automação gerenciadas simplificam a conexão entre o aplicativo de mensagens e ferramentas de negócio.

Vantagens

• baixo esforço de infraestrutura;
• construção visual;
• conectores para diferentes serviços;
• implantação rápida.

Limitações

• custos e limites por execução;
• menor controle sobre filas e retenção;
• necessidade de tratar duplicidades;
• dependência da disponibilidade da plataforma.

São alternativas interessantes para fluxos simples, protótipos e operações em validação. Para eventos críticos, considere manter um registro próprio ou utilizar uma camada de ingestão dedicada.

5. Event bus ou arquitetura própria

Uma camada de eventos recebe o webhook, persiste o evento e distribui a informação para diferentes consumidores.

Vantagens

• maior resiliência;
• isolamento entre consumidores;
• reprocessamento;
• escalabilidade;
• governança;
• observabilidade centralizada.

Limitações

• maior custo inicial;
• maior complexidade técnica;
• necessidade de políticas de retenção;
• necessidade de monitoramento mais completo.

Essa arquitetura faz mais sentido quando o app de mensagens é parte crítica de uma plataforma, operação SaaS ou infraestrutura omnichannel.

Qual solução escolher para cada estágio?

Cenário	Solução recomendada	Motivo
Teste inicial	n8n, Make ou Zapier	Rapidez e baixo esforço
Pequena operação	Webhook direto + banco	Controle e simplicidade
Atendimento em crescimento	Endpoint + fila + worker	Resiliência e reprocessamento
SaaS multiempresa	Event bus ou camada própria	Isolamento, escala e observabilidade
Operação crítica	Webhook + fila + alertas + DLQ	Maior controle e continuidade
Fallback temporário	Polling controlado	Descoberta de eventos quando o webhook não estiver disponível

A arquitetura também pode evoluir. Não é necessário começar com um ‘event bus’ para testar uma única notificação. Mas é importante saber quais componentes serão adicionados quando o volume e a criticidade aumentarem.

Observabilidade: como saber se o sistema está saudável?

Observabilidade é a capacidade de entender o comportamento do sistema por meio de logs, métricas e traces.

Logs estruturados

Cada evento deve gerar registros com campos consistentes.

Exemplo:

{   “eventId”: “evt_123”,   “instanceId”: “instance_abc”,   “messageId”: “msg_456”,   “eventType”: “DeliveryCallback”,   “receivedAt”: “2026-11-11T12:00:00Z”,   “processingStatus”: “COMPLETED”,   “durationMs”: 142 }

Evite registrar tokens, conteúdo sensível ou payloads completos sem necessidade. Sempre que possível, utilize IDs para correlação.

Métricas de entrada

Monitore:

• quantidade de eventos recebidos;
• respostas 2xx;
• respostas 4xx e 5xx;
• latência do endpoint;
• timeouts;
• tamanho da fila;
• eventos por instância;
• eventos por tipo.

Métricas de processamento

Acompanhe:

• tempo entre recebimento e início do processamento;
• tempo total do worker;
• taxa de sucesso;
• quantidade de retries;
• eventos na DLQ;
• duplicidades;
• falhas por dependência;
• eventos sem identificador.

Métricas de negócio

O monitoramento técnico precisa ser relacionado ao resultado da operação. Acompanhe também:

• taxa de resposta;
• conversas iniciadas;
• leads qualificados;
• pedidos atualizados;
• notificações confirmadas;
• mensagens lidas;
• tempo até atendimento humano;
• taxa de resolução.

Uma infraestrutura pode estar tecnicamente saudável e ainda proporcionar uma experiência ruim. Por isso, métricas técnicas e de negócio precisam ser analisadas em conjunto.

Quais alertas realmente ajudam?

Um alerta genérico como “erro no webhook” oferece pouca informação. O aviso deve indicar o problema, o impacto e a ação recomendada.

Alerta de desconexão

• Instância: loja-principal
• Evento: Disconnected
• Início: 11:42
• Duração: 5 minutos
• Impacto: envios transacionais pendentes
• Ação: verificar conexão da sessão e pausar novas campanhas

Alerta de aumento de falhas

• Instância: suporte
• Delivery errors: 18% nos últimos 10 minutos
• Base anterior: 2%
• Principal erro: destinatário inválido
• Ação: revisar validação de números e fila pendente

Alerta de fila acumulada

• Fila de entrada: 2.450 eventos
• Idade do evento mais antigo: 8 minutos
• Workers ativos: 2 de 8
• Ação: escalar consumidores e investigar dependência lenta

Alerta de ausência de eventos

Se uma operação costuma receber mensagens diariamente e passa horas sem qualquer evento, isso pode indicar uma desconexão ou falha de configuração. Um monitor de silêncio pode ajudar a identificar esse tipo de problema antes que ele seja percebido pelos clientes.

Como configurar os webhooks do Z-API?

A configuração pode ser feita pelo painel ou pelos endpoints disponibilizados pela API. Para atualizar o webhook de delivery:

PUT /instances/{instanceId}/token/{token}/update-webhook-delivery

Exemplo em JavaScript:

const url =   `https://api.z-api.io/instances/process.env.ZAPIINSTANCEID`+`/token/{process.env.ZAPI_TOKEN}/update-webhook-delivery`; const response = await fetch(url, {   method: “PUT”,   headers: {     “Client-Token”: process.env.ZAPI_CLIENT_TOKEN,     “Content-Type”: “application/json”   },   body: JSON.stringify({     value: “https://seu-dominio.com/webhooks/zapi/delivery”   }) }); const result = await response.json(); if (!response.ok) {   throw new Error(JSON.stringify(result)); } console.log(result)

A URL precisa utilizar HTTPS. Em produção, utilize uma rota específica por instância ou um mecanismo seguro para identificar a origem do evento.

Endpoint receptor

Um endpoint mínimo pode receber o evento e responder rapidamente:

app.post(“/webhooks/zapi/delivery”, async (req, res) => {   const event = req.body;   // Valide autenticação e estrutura antes de persistir.   await events.insertIfAbsent({     key: `event.instanceId:{event.messageId}:${event.type}`,     payload: event,     receivedAt: new Date()   });   res.sendStatus(200); });

Em produção, acrescente:

• autenticação;
• validação de schema;
• idempotência;
• fila;
• limites de tamanho;
• logs;
• tratamento de erros.

Teste o webhook

Antes de colocar a integração em produção, teste diferentes situações:

• mensagem de texto;
• áudio;
• documento;
• mensagem recebida;
• leitura;
• erro de envio;
• desconexão controlada, quando possível.

Confirme se:

1. o evento chega ao endpoint;
2. o identificador é armazenado;
3. o evento pode ser relacionado ao envio;
4. o processamento ocorre corretamente;
5. o alerta esperado é gerado em caso de falha.

Aproveite e confira também: qual API gateway é melhor para integrações no-code ou low-code.

Como medir a confiabilidade?

Defina indicadores objetivos para acompanhar a saúde da integração.

Disponibilidade do endpoint

Percentual de tempo em que o endpoint respondeu corretamente. Um endpoint indisponível impede o recebimento dos eventos.

Taxa de aceitação

Percentual de webhooks que receberam resposta 2xx.

Latência de ingestão

Tempo entre o recebimento do evento e sua persistência no sistema.

Tempo de processamento

Tempo entre a entrada do evento e a conclusão da ação de negócio.

Taxa de duplicidade

Quantidade de eventos repetidos identificados pelo sistema. Uma taxa elevada pode indicar problemas de retry ou ausência de idempotência.

Taxa de eventos na DLQ

Eventos enviados para a fila de falhas devem representar exceções. Se esse indicador crescer, a equipe deve investigar a causa.

Tempo de recuperação

Mede quanto tempo passa entre uma desconexão e o restabelecimento da operação. Esse indicador ajuda a avaliar a eficiência do processo de resposta a incidentes.

Boas práticas de segurança

Use HTTPS

O Z-API exige HTTPS para webhooks de envio. O certificado deve ser válido e renovado antes da expiração.

Autentique o receptor

Utilize um mecanismo de autenticação compatível com sua arquitetura, como token, assinatura ou cabeçalho secreto. Não dependa apenas de uma URL difícil de adivinhar.

Limite a origem

Quando a infraestrutura permitir, utilize allowlist de IP ou uma camada de gateway para restringir quem pode chamar o endpoint.

Proteja os logs

Webhooks podem conter telefones, identificadores, conteúdo e dados de negócio. Mascare informações desnecessárias e limite o acesso aos registros.

Evite processamento duplicado

Idempotência é essencial para evitar efeitos duplicados. Uma repetição de evento não deve criar dois tickets, enviar duas respostas ou atualizar duas vezes uma operação sensível.

Monitore sua operação em tempo real com os webhooks do Z-API

A melhor solução de webhooks para monitoramento em tempo real é aquela que combina eventos relevantes, baixa latência, segurança, persistência, idempotência, observabilidade e alertas acionáveis.

Para uma operação pequena, um webhook direto pode ser suficiente. Para um MVP, n8n, Make ou Zapier podem acelerar a implementação. Para uma operação crítica ou SaaS, pode fazer sentido utilizar endpoint próprio, fila, workers, DLQ, métricas e alertas.

O Z-API disponibiliza webhooks para delivery, recebimento, status e desconexão. Esses eventos permitem acompanhar a jornada das mensagens e o estado da conexão, desde que a aplicação registre e processe as informações corretamente.

O próximo passo é configurar o webhook, realizar um envio de teste e acompanhar o evento até o estado final.

Não espere uma falha em produção para descobrir que sua equipe não sabe se uma mensagem foi processada, entregue, recebida ou lida.

Configure os webhooks do Z-API e monitore os canais de mensagens da sua empresa.