Wafly › Tutoriais › Webhook de WhatsApp

Webhook de WhatsApp: como receber mensagens na sua aplicação

Atualizado em julho de 2026

Enviar mensagem por API é a metade fácil. O que transforma um disparador em bot de verdade é o caminho contrário: a mensagem do cliente chegar na sua aplicação, em tempo real. Isso é o webhook — a API chama uma URL sua a cada evento da instância.

Os 4 webhooks da instância

Passo 1 — Configurar a URL

Cada webhook é um PUT com a URL de destino no corpo (string vazia "" remove):

curl -X PUT "https://wafly.com.br/api-bridge-whats/instances/SUA_INSTANCIA/token/SEU_TOKEN/update-webhook-received" \
  -H "Client-Token: SEU_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "https://meuservidor.com/webhook/whatsapp" }'

Passo 2 — Receber (exemplo em Node.js)

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhook/whatsapp", (req, res) => {
  res.sendStatus(200); // responda JÁ; processe depois

  const evento = req.body;
  console.log(JSON.stringify(evento, null, 2));
  // evento.phone   → quem mandou (ou o grupo de origem)
  // evento.isGroup → true se veio de grupo
  // + conteúdo da mensagem e metadados do evento
});

app.listen(3000);

Na primeira mensagem de teste, logue o payload inteiro e inspecione — é o jeito mais rápido de ver todos os campos disponíveis para o seu caso (texto, mídia, remetente, grupo). Em desenvolvimento local, exponha a porta com um túnel (ngrok, cloudflared) para o webhook alcançar sua máquina.

Boas práticas que evitam dor

• Responda 200 imediatamente e processe o evento de forma assíncrona (fila, job). Receiver lento = timeout = retries = eventos duplicados.
• Idempotência: trate o ID da mensagem como chave — se o mesmo evento chegar duas vezes, processe uma.
• Segredo na URL: use um caminho imprevisível (ex.: /webhook/whatsapp/x7k2m9) e valide-o — qualquer um que descubra a URL pode mandar POST nela.
• Filtre o que não é seu caso: mensagens de grupo (isGroup) e eventos que você não usa devem sair cedo do handler.
• Monitore o webhook de desconexão: é seu alarme de sessão caída antes do cliente reclamar.

Sem servidor? Use n8n

O Webhook node do n8n gera a URL pública por você — cadastre-a no update-webhook-received e cada mensagem vira uma execução do workflow. O caminho completo está no tutorial WhatsApp no n8n.

Perguntas frequentes

Continue

Endpoints verificados em julho/2026. Encontrou algo impreciso? Fale com a gente que corrigimos.