Evolution API v2 vs v3: o que mudou e como migrar sua instância em VPS

A Evolution API v3 introduziu mudanças estruturais que quebram a compatibilidade direta com instâncias v2: o schema do banco de dados foi reestruturado, o formato de webhooks mudou e as variáveis de ambiente agora seguem nomenclatura diferente. Migrar uma instância v2 rodando em VPS exige backup completo, ajuste manual de configurações e revalidação de todas as integrações externas antes de colocar em produção.

TL;DR: Evolution API v3 não é drop-in replacement da v2. A migração exige backup do PostgreSQL/MySQL, atualização de variáveis de ambiente, revisão de webhooks e teste de integração com n8n, Typebot e outros clientes HTTP antes do cutover.

Este artigo detalha o que mudou entre as versões, os pontos críticos de quebra e o roteiro técnico para migrar uma instância auto-hospedada em VPS sem perder mensagens ou sessões ativas.

O que mudou da Evolution API v2 para v3?

A principal mudança está na arquitetura de persistência e mensageria. A v3 separou o gerenciamento de sessões do armazenamento de mensagens, movendo metadados para tabelas dedicadas e adotando Redis como camada de cache obrigatória para alta disponibilidade.

Schema do banco de dados

A v2 usava uma única tabela instances para sessões e configurações. A v3 divide em três entidades: instance, session e webhook_config, cada uma com índices próprios. Resultado: queries mais rápidas, mas impossível reaproveitamento direto do dump da v2.

Formato de webhooks

Webhooks agora entregam payload em estrutura aninhada sob chave data, com envelope contendo event, instance e timestamp no nível raiz. Integrações que faziam parse direto do corpo precisam ajustar o caminho JSON.

Variáveis de ambiente

A v3 consolidou prefixos: tudo relacionado a banco agora usa DATABASE_, webhooks usam WEBHOOK_, autenticação AUTH_. A tabela abaixo mapeia as principais:

Redis obrigatório

A v2 tolerava deploy sem cache externo. A v3 exige Redis para coordenar sessões entre restarts e permitir horizontal scaling futuro. Em VPS single-node, um container Redis local resolve, mas é mais um componente no stack.

Por que a v3 quebra compatibilidade?

A decisão de quebrar reflete priorização de estabilidade em produção multi-instância sobre facilidade de upgrade. A v2 tinha problemas de race condition ao reconectar sessões após restart, perda de mensagens em falha de disco e dificuldade de monitorar webhook delivery.

A v3 resolve esses pontos ao custo de exigir migração ativa. Para quem roda instâncias críticas integrando CRM, chatbots via n8n ou atendimento com Typebot, o ganho de confiabilidade justifica o esforço de migração — mas o processo não é automático.

Checklist pré-migração

Antes de tocar na instância v2 em produção, documente e prepare o ambiente:

1. Inventário de integrações: liste todos os webhooks ativos, workflows no n8n, Typebot, Chatwoot ou outros consumidores da API. Anote endpoints, eventos registrados e variáveis usadas.

2. Backup completo do banco: pg_dump ou mysqldump com schema + dados. Guarde localmente e em bucket S3/equivalente. Sessões ativas do WhatsApp não sobrevivem sem essa cópia.

3. Snapshot do VPS: se o provider permitir, tire snapshot do disco. Rollback em minutos vale ouro se algo der errado no cutover.

4. Redis standalone: suba um container Redis 7.x na mesma rede Docker da Evolution. Teste conectividade com redis-cli ping antes de prosseguir.

5. Ambiente de stage: se possível, clone a instância v2 em VPS separado, faça a migração lá primeiro e valide todas as chamadas HTTP. Diminui risco de downtime não planejado.

Roteiro de migração passo a passo

1. Pare a instância v2

docker compose -f evolution-v2.yml down

Certifique-se de que nenhum processo está ouvindo a porta da API. Sessions do WhatsApp ficarão offline por alguns minutos — agende a janela fora do horário de pico.

2. Dump do banco v2

docker exec evolution-postgres pg_dump -U evolution evolution_db > backup-v2.sql

Valide o arquivo: procure por CREATE TABLE instances e confirme presença de INSERT INTO. Sem esse backup, não há volta.

3. Suba a v3 com banco limpo

Clone o repositório oficial da Evolution API v3 e ajuste o docker-compose.yml:

services:
  evolution:
    image: atendai/evolution-api:v3.0
    environment:
      DATABASE_HOST: postgres
      DATABASE_NAME: evolution_v3
      DATABASE_USER: evolution
      DATABASE_PASSWORD: ${DB_PASSWORD}
      AUTH_API_KEY: ${API_KEY}
      AUTH_JWT_SECRET: ${JWT_SECRET}
      WEBHOOK_GLOBAL_URL: ${WEBHOOK_URL}
      REDIS_HOST: redis
      REDIS_PORT: 6379
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: evolution_v3
      POSTGRES_USER: evolution
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data

volumes:
  pg_data:
  redis_data:

Suba com docker compose up -d. A v3 criará as tabelas automaticamente no primeiro boot.

4. Recrie instâncias manualmente

A Evolution v3 não importa dump da v2. É necessário recriar cada instância via API:

curl -X POST https://sua-instancia.com/instance/create \
  -H "apikey: ${AUTH_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "atendimento",
    "qrcode": true,
    "webhook": {
      "url": "https://n8n.sua-empresa.com/webhook/evolution",
      "events": ["messages.upsert", "connection.update"]
    }
  }'

Escaneie o QR Code novamente no WhatsApp. Sessões antigas da v2 não migram — é reconexão do zero.

5. Ajuste webhooks nos consumidores

Se você usa n8n ou Typebot, atualize os nós Webhook para acessar {{ $json.data.body }} em vez de {{ $json.body }}. Workflows existentes vão falhar até esse ajuste ser feito em cada trigger.

No n8n, abra o workflow, edique o nó Webhook Evolution, expanda Response Data e mude o JSONPath de body para data.body. Salve e teste com mensagem real.

6. Valide entrega de mensagens

Envie mensagens de teste via API, via webhook inbound e via interface. Monitore logs com:

docker logs -f evolution --tail=100

Procure por erros de conexão Redis, falha de autenticação ou timeout no PostgreSQL. Se o Redis não estiver acessível, a API retorna HTTP 503.

Integração com Hermes Agent e n8n

A API do WhatsApp da Rollin Host pode rodar tanto sobre Evolution v2 quanto v3, mas para quem usa Hermes Agent (assistente de IA com memória contextual) ou automação via n8n, a v3 traz vantagem: eventos de presença (presence.update) agora chegam de forma confiável, permitindo que o bot responda apenas quando o usuário está online.

Configuração do webhook para Hermes

O Hermes Agent espera campo message.conversation ou message.extendedTextMessage.text. Na v3, ambos estão dentro de data.message:

{
  "event": "messages.upsert",
  "instance": "atendimento",
  "data": {
    "key": {
      "remoteJid": "5511999999999@s.whatsapp.net"
    },
    "message": {
      "conversation": "Olá, preciso de suporte"
    }
  }
}

Se o Hermes ainda aponta para a v2, atualize a URL do webhook na dashboard e remapeie os campos no adaptador JSON.

Workflow n8n com Evolution v3

Um workflow típico para triagem automática fica assim:

1. Webhook escuta POST /webhook/evolution (valide assinatura com HMAC se configurado).
2. Function extrai remoteJid e conversation de data.
3. HTTP Request consulta Hermes Agent: POST /agent/chat com { "sessionId": remoteJid, "message": conversation }.
4. HTTP Request envia resposta via Evolution: POST /message/sendText com { "number": remoteJid, "text": respostaHermes }.

A latência típica de ponta a ponta cai de ~1,2s na v2 para ~800ms na v3, graças ao cache Redis e índices otimizados no banco.

Trade-offs e quando NÃO migrar ainda

A v3 é mais estável, mas mais complexa de operar. Considere adiar se:

• Sua instância v2 está estável há meses, com poucas mensagens/dia (<500) e sem integrações críticas. O ganho marginal não justifica risco de downtime.
• Você não tem Redis no stack e o VPS tem apenas 1 GB de RAM. O overhead adicional pode derrubar a instância em pico.
• Integrações dependem de bibliotecas client antigas que ainda não suportam o novo formato de webhook (algumas libs PHP/Python comunitárias demoraram a atualizar em 2026).

Para instâncias novas, sempre comece na v3. Para migração, prefira janela de manutenção com fallback planejado.

Principais aprendizados

• Evolution API v3 quebra compatibilidade com v2 no schema, webhooks e variáveis — migração não é upgrade in-place.
• Redis passa a ser obrigatório para coordenar sessões; prepare container ou instância gerenciada antes do cutover.
• Webhooks agora entregam payload aninhado sob chave data — ajuste integrações com n8n, Typebot e Hermes Agent.
• Sessões WhatsApp não migram — é necessário reconectar via QR Code após recriar as instâncias na v3.
• Ganho real de performance: latência de entrega cai ~30% e reconexão após restart é 4× mais rápida.

Perguntas frequentes

Evolution API v3 é retrocompatível com v2?

Não. O schema do banco, formato de webhooks e variáveis de ambiente mudaram. É necessário migração ativa, com recriação de instâncias e ajuste de integrações.

Consigo migrar sessões ativas do WhatsApp da v2 para v3?

Não. Sessões salvas na v2 não são importadas pela v3. Após a migração, cada número precisa escanear o QR Code novamente para reconectar.

Redis é obrigatório mesmo em VPS com uma única instância?

Sim. A v3 usa Redis para cache de sessão e coordenação de eventos. Sem ele, a API não inicia. Um container Redis local consome ~50 MB de RAM em idle.

Como ajustar webhooks no n8n após migrar para v3?

Abra cada workflow que escuta a Evolution, edite o nó Webhook e mude o JSONPath de body para data.body, from para data.key.remoteJid. Salve e teste com mensagem real.

Vale a pena migrar se minha v2 está estável?

Depende. Se você processa mais de 500 mensagens/dia, usa integração com IA ou precisa de alta disponibilidade, a v3 justifica. Para uso casual, pode adiar até a v2 sair de suporte.

A Rollin Host oferece migração gerenciada?

Sim. Clientes do plano VPS para n8n com Evolution API podem solicitar migração assistida, incluindo backup, recriação de instâncias e validação de integrações. Entre em contato pelo suporte para agendar a janela.

Precisa de ajuda para migrar sua instância Evolution?

A Rollin Host oferece VPS otimizado para automação, com Evolution API v3, n8n e Typebot pré-instalados, Redis configurado e backup automático diário. Se sua instância v2 está rodando em infraestrutura própria e você quer evitar o risco de migração manual, podemos provisionar ambiente v3 limpo e auxiliar na transferência de integrações.

Fale com o time técnico pelo WhatsApp e solicite análise da sua stack atual — sem compromisso, sem cobrança de consultoria prévia.