O webhook da Evolution API precisa de HTTPS?

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.

Quais eventos devo configurar para uma automação básica de atendimento?

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.

O webhook para de funcionar quando a instância desconecta?

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.

Posso ter múltiplos webhooks numa mesma instância?

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.

Como garantir que não perco eventos se o backend ficar fora por alguns minutos?

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.

Evolution API/Artigo

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"
      ]
    }
  }'

Dica

[VERIFICAR: a estrutura do body de criação de instância pode variar entre Evolution API v1 e v2. Confirme em doc.evolution-api.com antes de usar em produção.]

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"

Dica

[VERIFICAR: o endpoint /webhook/set/{instance} pode ser /webhook/set na v2. Confirme no repositório da versão instalada.]

Eventos disponíveis no webhook

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

Dica

MESSAGES_UPSERT — nova mensagem recebida ou enviada (o mais importante para automações). MESSAGES_UPDATE — atualização de status de mensagem (entregue, lida). CONNECTION_UPDATE — mudança no estado da conexão (connected, close, qr). SEND_MESSAGE — confirmação de envio de mensagem. GROUPS_UPSERT — criação ou atualização de grupo. CALL — chamada de voz ou vídeo recebida.

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

Atenção

A URL do ngrok muda a cada sessão (exceto no plano pago). Para desenvolvimento contínuo, use uma conta ngrok com subdomínio fixo ou suba o servidor diretamente na VPS.

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

Dica

Causas comuns: URL com HTTP em vez de HTTPS, endpoint retornando status != 2xx (a Evolution API considera falha e pode parar de entregar), ou firewall bloqueando saída do container.

$ runstack deploy --plan starter

Não quer configurar manualmente?

Não quer configurar manualmente? Implante o Evolution API em menos de 3 minutos com a Runstack. Infraestrutura da OPEN DATACENTER, com servidores no Brasil.

Começar agora Ver planos e preços

Perguntas frequentes

Conteúdos relacionados

VPS para Evolution API no Brasil →Como instalar a Evolution API →Evolution API desconectando: como resolver Evolution API com n8n Múltiplas instâncias num servidor

[VERIFICAR antes de publicar]

1. Confirme os endpoints /webhook/set e /instance/create na documentação da versão instalada — diferem entre v1 e v2.
2. Confirme se a estrutura do body de webhook (webhook_by_events vs byEvents) é a correta para a versão usada.