Webhooks na EvolutionAPI

Como configurar e receber webhooks da EvolutionAPI com retries, idempotência e segurança em produção.

A EvolutionAPI envia eventos via webhook HTTP POST para uma URL que você define. O webhook é a forma como sua automação (n8n, sua própria API, etc) sabe que chegou mensagem.

Eventos disponíveis

Evento	Quando dispara
`MESSAGES_UPSERT`	Mensagem recebida ou enviada
`MESSAGES_UPDATE`	Status mudou (entregue, lido)
`CONNECTION_UPDATE`	Conectou/desconectou
`PRESENCE_UPDATE`	”Digitando…” / online
`QRCODE_UPDATED`	Novo QR para parear

Configurar webhook global

Configure no momento de criar a instância:

curl -X POST https://sua-evolution.rollinhost.com.br/instance/create \
  -H "Content-Type: application/json" \
  -H "apikey: SUA_API_KEY" \
  -d '{
    "instanceName": "atendimento",
    "qrcode": true,
    "webhook": {
      "url": "https://seu-n8n.exemplo.com/webhook/whats-in",
      "events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"],
      "webhook_by_events": false
    }
  }'

Estrutura do payload

{
  "event": "messages.upsert",
  "instance": "atendimento",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB0..."
    },
    "pushName": "João Silva",
    "message": {
      "conversation": "Oi, gostaria de saber sobre os planos"
    },
    "messageTimestamp": 1735689600
  }
}

Retries e idempotência

Boas práticas:

Sempre retorne 200 rapidamente (< 5s) — processe em fila
Idempotência por data.key.id — webhooks podem chegar duplicados em reconexão
Persistência do raw event antes de processar (em caso de bug, você reprocessa)

Segurança

A EvolutionAPI não assina os webhooks por padrão. Para garantir que a requisição veio dela:

Restrinja por IP no firewall (apenas o IP do servidor da Evolution)
Use uma URL com path secreto (/webhook/abc123-supersecreto)
Validar apikey custom no header (configure no n8n para checar)

Próximos passos

Última atualização: 15 de abril de 2026