Eventos em tempo real
Integrar WhatsApp com Webhook
Webhook é o mecanismo mais simples de integração servidor-a-servidor: em vez de o seu sistema ficar perguntando a toda hora se chegou algo novo, ele recebe uma requisição HTTP POST no exato momento em que um evento acontece. Você expõe uma URL pública (um endpoint no seu backend) e o provedor entrega o payload do evento nela. É o padrão usado por praticamente todas as plataformas modernas para notificar mensagens recebidas, mudanças de status de entrega, atualizações de pagamento e afins, sem polling e com latência baixíssima.
Por que conectar
Conectar a ZapZap API a um webhook seu resolve os dois lados do WhatsApp de forma limpa: o recebimento chega empurrado no seu servidor e o envio sai via REST. Imagine um e-commerce que quer responder na hora quando o cliente manda "cadê meu pedido" no WhatsApp. Sem webhook, seu sistema teria que consultar a API em loop e você pagaria latência e processamento à toa. Com webhook, a ZapZap API dispara um POST para o seu endpoint no instante em que a mensagem chega, seu backend consulta o pedido no banco e responde chamando o endpoint de envio da ZapZap API, tudo em segundos. Como o número roda em instância gerenciada com aquecimento em comunidade e camada de anti-bloqueio, você reduz o risco de queda enquanto mantém o controle total do fluxo no seu código. Cada número ativo custa R$15 por mês, pré-pago, e você começa com crédito grátis para testar a integração.
Passo a passo
- 1
Crie o endpoint que vai receber os eventos
No seu backend, exponha uma rota pública que aceite POST, por exemplo POST https://seusistema.com/webhooks/zapzap. Ela precisa ler o corpo JSON da requisição e responder rápido com status 2xx (200 ou 204). Responder fora da faixa 2xx faz o evento ser tratado como falha e reenviado. Se ainda não tem uma URL pública em ambiente de desenvolvimento, suba um túnel com ngrok (ngrok http 3000) e use a URL https gerada.
- 2
Deixe o endpoint acessível e idempotente
Garanta que a URL responda em HTTPS e sem autenticação bloqueando o POST do provedor (ou libere o IP/rota do webhook). Trate o payload como potencialmente duplicado: guarde o ID do evento ou da mensagem e ignore reentregas já processadas. Assim, se o mesmo evento chegar duas vezes por retry, você não responde o cliente em dobro.
- 3
Cadastre a URL do webhook na sua instância ZapZap API
No painel da ZapZap API, abra a instância WhatsApp e vá na seção de Webhook. Cole a URL do seu endpoint e selecione os eventos que quer receber, como mensagem recebida e status de entrega. Salve. A partir daí, cada evento daquela instância será entregue no seu endpoint. Os nomes exatos dos eventos e o formato do payload estão na doc em https://api.zapzapapi.com/llms.txt.
- 4
Processe o evento e dispare a resposta via REST
Quando o POST chegar, extraia o número do remetente e o texto da mensagem do corpo. Rode a sua lógica (consultar pedido, acionar IA, gravar no CRM) e responda chamando o endpoint de envio da ZapZap API com os headers x-api-key e x-api-secret. Sempre devolva 2xx no webhook mesmo que o processamento pesado siga em background, para não travar a fila de entrega.
- 5
Teste ponta a ponta em produção
Mande uma mensagem real para o número da instância e confirme nos logs do seu servidor que o POST chegou com o payload esperado. Depois valide que a resposta automática saiu pelo WhatsApp. Monitore os logs de entrega do webhook no painel: entregas non-2xx ficam registradas para diagnóstico, então é ali que você investiga se o seu endpoint recusou algum evento.
Exemplo
// Seu endpoint recebe o evento (Express)
app.post('/webhooks/zapzap', (req, res) => {
res.sendStatus(200); // responda 2xx primeiro
const { numero, texto } = req.body; // campos ILUSTRATIVOS, ver doc
// sua logica aqui, depois responde pelo WhatsApp:
});
// Enviar resposta via REST (campos exatos na doc)
fetch('https://api.zapzapapi.com/api/v1/{instanceId}/send/text', {
method: 'POST',
headers: {
'x-api-key': 'SUA_API_KEY',
'x-api-secret': 'SEU_API_SECRET',
'Content-Type': 'application/json'
},
body: JSON.stringify({ numero: '5511999999999', texto: 'Recebido!' })
});
// Estrutura exata de rotas e campos: https://api.zapzapapi.com/llms.txtIlustrativo. Os campos e endpoints exatos estão na documentação.
Perguntas frequentes
Preciso de um servidor próprio para usar webhook?
Sim, o webhook exige uma URL pública que aceite POST. Pode ser um backend seu (Node, PHP, Python), uma função serverless ou um fluxo em ferramentas como n8n e Make. Em desenvolvimento, dá para usar um túnel como ngrok para expor o localhost.
Qual a diferença entre receber por webhook e enviar por REST?
São os dois sentidos da conversa. O webhook é a ZapZap API empurrando eventos para o seu sistema (mensagem recebida, status de entrega). O REST é o seu sistema chamando a ZapZap API para enviar mensagens. Você usa os dois juntos para montar respostas automáticas.
O que acontece se meu endpoint estiver fora do ar quando chegar um evento?
Se o seu endpoint não responder com status 2xx, a entrega é registrada como falha. Por isso vale responder 2xx rápido e processar o resto em background, além de tratar o payload como possivelmente duplicado para lidar com reentregas sem processar o mesmo evento duas vezes.
Quanto custa e como funciona a autenticação?
Cada número ativo custa R$15 por mês, pré-pago, e você começa com crédito grátis para testar. O recebimento por webhook é configurado no painel da instância. Já as chamadas REST de envio usam os headers x-api-key e x-api-secret, gerados na sua conta.
Onde encontro os nomes exatos dos eventos e campos do payload?
Na documentação em https://api.zapzapapi.com/llms.txt. Os exemplos deste guia são ilustrativos para mostrar o fluxo; os nomes reais de eventos, rotas e campos ficam na doc, que é a fonte oficial.
Comece com crédito grátis
Crie sua conta, conecte um número em minutos e teste a API com aquecimento e anti-bloqueio. R$15 por número ativo/mês, pré-pago, sem fidelidade.