Pular para o conteúdo
EntrarCriar minha VPS

Como configurar webhooks na Evolution API

Os webhooks da Evolution API enviam uma requisição HTTP POST ao seu backend ou n8n cada vez que um evento ocorre, mensagem recebida, status de conexão mudou, mensagem entregue. Para configurar, defina a URL do webhook na instância via API REST e certifique-se de que o endpoint está acessível publicamente com HTTPS.

Configurando o webhook na criação da instância

A forma mais limpa é definir o webhook já na criação da instância. Inclua os campos webhook e events no body da requisição:

bash
curl -X POST "https://seu-servidor/instance/create" \
  -H "apikey: sua-chave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "minha-instancia",
    "token": "token-opcional",
    "qrcode": true,
    "webhook": {
      "url": "https://seu-n8n.com/webhook/evolution",
      "byEvents": false,
      "base64": false,
      "events": [
        "MESSAGES_UPSERT",
        "CONNECTION_UPDATE"
      ]
    }
  }'

Atualizando o webhook de uma instância existente

Para alterar o webhook de uma instância já criada, use o endpoint de configuração de webhook:

bash
curl -X POST "https://seu-servidor/webhook/set/minha-instancia" \
  -H "apikey: sua-chave-api" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-backend.com/webhook/whatsapp",
    "webhook_by_events": false,
    "webhook_base64": false,
    "events": [
      "MESSAGES_UPSERT",
      "MESSAGES_UPDATE",
      "CONNECTION_UPDATE",
      "SEND_MESSAGE"
    ]
  }'

# Verificar a configuração atual do webhook
curl -X GET "https://seu-servidor/webhook/find/minha-instancia" \
  -H "apikey: sua-chave-api"

Eventos disponíveis no webhook

A Evolution API envia diferentes tipos de evento. Os mais usados em automações com n8n são:

Como testar o webhook localmente com ngrok

Durante o desenvolvimento, use o ngrok para expor seu endpoint local com URL pública temporária:

bash
# Instalar ngrok (exemplo no Ubuntu)
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

# Expor a porta 3000 do seu backend local
ngrok http 3000

# A URL gerada (ex.: https://abc123.ngrok.io) pode ser usada como webhook URL

Troubleshooting: webhook não recebe eventos

Se o webhook está configurado mas não chega nada no seu endpoint, verifique nesta ordem:

bash
# 1. Confirmar que o webhook está configurado
curl -X GET "https://seu-servidor/webhook/find/minha-instancia" \
  -H "apikey: sua-chave-api"

# 2. Verificar se a URL do webhook é acessível publicamente
curl -X POST "https://seu-backend.com/webhook/whatsapp" \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# 3. Ver logs do container para erros de entrega de webhook
docker compose logs evolution --tail=50 | grep -i webhook

Não quer configurar manualmente?

Implante o Evolution API em menos de 5 minutos com a Runstack. Infraestrutura da OPEN Datacenter, com servidores em São Paulo.

Criar minha VPSVer apps prontos

Perguntas frequentes

Para produção, HTTPS é obrigatório, a Evolution API rejeitará URLs HTTP inseguras em algumas configurações. Para desenvolvimento local, use ngrok para gerar uma URL HTTPS temporária.

Para automação de atendimento, os eventos essenciais são MESSAGES_UPSERT (para receber mensagens) e CONNECTION_UPDATE (para saber quando a instância desconecta). Os demais eventos são opcionais e geram volume de requisições ao seu backend.

Sim. Quando a instância está desconectada do WhatsApp, não há novos eventos de mensagem. Mas o evento CONNECTION_UPDATE é enviado quando a instância desconecta, use-o para acionar alertas ou lógica de reconexão no n8n.

A Evolution API suporta um único webhook URL por instância. Para fan-out a múltiplos destinos, configure o n8n como receptor central e distribua os eventos via outros nodes no workflow.

A Evolution API não tem fila de retry nativa para webhooks. Se seu endpoint estiver offline, os eventos do período são perdidos. Para ambientes críticos, use o Redis como buffer e implemente um consumer queue no seu backend.

Continue lendo