Evolution API: Resolva Instabilidade e Webhooks Falhando

Evolution API: Resolvendo Instabilidade e Webhooks Falhando em Produção

A Evolution API é uma solução robusta para quem busca integrar o WhatsApp em suas aplicações de forma programática e escalável. No entanto, como qualquer ferramenta self-hosted, ela pode apresentar desafios em produção, especialmente relacionados à instabilidade da conexão, falhas no envio de mensagens ou webhooks que simplesmente não disparam. Este guia prático, baseado em minha experiência com centenas de implantações, foca em resolver os problemas mais comuns, garantindo que sua instância da Evolution API funcione de maneira confiável. Assumimos que você já decidiu pelo self-hosting e agora busca a melhor forma de implantar e manter essa ferramenta rodando em um servidor VPS. Para uma operação estável em produção, recomendamos um VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs, um ambiente ideal para rodar a Evolution API com tranquilidade, especialmente se você utiliza Docker Compose para gerenciar a aplicação e seu banco de dados.

Veja a infraestrutura: VPS para Evolution API no Brasil para colocar este projeto no ar.

Por que a Evolution API Desconecta Sozinha?

A desconexão de instâncias da Evolution API é um dos problemas mais frustrantes. Na maioria das vezes, a causa raiz está no ambiente de hospedagem. Servidores com pouca RAM são os principais culpados, pois o sistema operacional ou o próprio container da Evolution API podem ser encerrados pelo gerenciador de memória (OOM Killer) quando os recursos se esgotam. Para produção, recomendamos um mínimo de 4GB de RAM dedicados à stack completa (Evolution API, banco de dados, proxy). Outras causas incluem instabilidade na rede, falhas no banco de dados (como PostgreSQL, essencial para a persistência de dados) ou até mesmo um problema na própria biblioteca do WhatsApp Web que a Evolution API utiliza para se conectar.

O Que Fazer Quando a Evolution API Não Envia Mensagens?

Quando sua Evolution API não envia mensagens, o primeiro passo é verificar o status da instância. Ela está conectada? Se sim, o problema pode ser na fila de mensagens ou na configuração da API. Um erro ao criar instância Evolution API pode impedir qualquer comunicação. Certifique-se de que o QR Code foi escaneado corretamente e que a sessão está ativa. Se a instância está conectada, mas as mensagens não saem, consulte os logs da aplicação e do servidor para identificar mensagens de erro específicas. O uso de um banco de dados como PostgreSQL é crucial para que as mensagens não se percam caso a aplicação seja reiniciada. Em minha experiência, problemas de envio muitas vezes estão ligados à limitação de recursos do servidor, onde a aplicação não consegue processar a fila de requisições rapidamente.

Diagnóstico de Webhook Não Dispara na Evolution API

O evolution api webhook não dispara é um sintoma comum quando a integração entre a Evolution API e seu sistema externo falha. Existem duas camadas principais para investigar: a saída da Evolution API e a entrada do seu sistema receptor. Primeiro, certifique-se de que a URL de webhook configurada na Evolution API está correta e que o endpoint está acessível pela internet. Um erro de digitação na URL, um firewall bloqueando a conexão externa, ou o servidor do seu sistema estando offline são causas frequentes. Dentro da Evolution API, verifique os logs para ver se a tentativa de enviar o webhook foi registrada e se houve alguma falha. Se a Evolution API estiver rodando em um container, garanta que ele tenha acesso à rede externa. Para um diagnóstico mais aprofundado de webhooks, diagnosticar webhooks que não chegam pode ser muito útil.

Passo a Passo: Implantando a Evolution API em um VPS com Docker Compose

Para garantir a estabilidade e facilitar o gerenciamento, recomendamos fortemente o uso de Docker e Docker Compose para implantar a Evolution API em seu VPS. Este método simplifica a configuração e o isolamento das dependências.

Requisitos do Servidor

Para rodar a Evolution API em produção com PostgreSQL, você precisará de um servidor com pelo menos 4GB de RAM e 2 vCPUs. Para volumes maiores de mensagens e maior robustez, um plano com 4GB de RAM e 4 vCPUs, como o nosso VPS Brasil Básico, é o ideal. Além disso, um espaço em disco de pelo menos 20GB é recomendado para o sistema operacional, Docker, logs e o banco de dados, que pode crescer consideravelmente.

Configuração do Docker Compose

Crie um diretório para seu projeto, por exemplo, ~/evolution-api, e dentro dele, crie um arquivo chamado docker-compose.yml:

version: '3.8'

services:
  evolution-api:
    image: ghcr.io/evolution-api/evolution-api:latest
    container_name: evolution-api
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - MONGO_URL=mongodb://mongo:27017/evolution-api
      - JWT_SECRET=sua_chave_jwt_aqui
      - WA_INSTANCE_NAME=sua_instancia
      - NODE_ENV=production

  mongo:
    image: mongo:latest
    container_name: evolution-api-mongo
    restart: unless-stopped
    volumes:
      - ./mongo-data:/data/db
    environment:
      - MONGO_INITDB_ROOT_USERNAME=admin
      - MONGO_INITDB_ROOT_PASSWORD=sua_senha_mongo_aqui

volumes:
  data:
  logs:
  mongo-data:

Observação importante: O exemplo acima utiliza MongoDB. Para produção, é altamente recomendado usar PostgreSQL para maior confiabilidade e desempenho. A configuração do Docker Compose para PostgreSQL seria diferente. Certifique-se de gerar uma chave JWT forte e armazenar suas credenciais de MongoDB de forma segura.

Pré-requisitos de Instalação no VPS

Antes de subir os containers, garanta que você tem o Docker e o Docker Compose instalados em seu VPS Ubuntu. Se ainda não os tem, siga estes passos:

# Atualiza a lista de pacotes
sudo apt update

# Instala pacotes necessários para o Docker
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y

# Adiciona a chave GPG oficial do Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Adiciona o repositório Docker
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instala o Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io -y

# Instala o Docker Compose Plugin (versão 2.x)
sudo apt install docker-compose-plugin -y

# Verifica a instalação
docker --version
docker compose version

Subindo a Aplicação

Navegue até o diretório onde você salvou o docker-compose.yml e execute:

docker compose up -d

O comando -d significa 'detached', rodando os containers em segundo plano. Para verificar os logs e ver se tudo subiu corretamente, use:

docker compose logs -f evolution-api

Se você encontrar problemas de rede ou de permissão, consulte nosso artigo sobre Docker: Resolvendo Erros de Rede e Disco em VPS.

Otimizando a Conexão e Webhooks com Proxy Reverso

Para expor a Evolution API de forma segura e gerenciar tráfego, a configuração de um proxy reverso, como Nginx ou Caddy, é essencial. Ele pode lidar com SSL/TLS, rotear requisições para a porta 5000 do container e até mesmo adicionar camadas de segurança.

Configuração Básica do Nginx como Proxy Reverso

Assumindo que você já tem o Nginx instalado em seu VPS (sudo apt install nginx), crie um novo arquivo de configuração para a Evolution API em /etc/nginx/sites-available/evolution-api:

server {
    listen 80;
    server_name seu.dominio.com;

    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Ative o site e reinicie o Nginx:

sudo ln -s /etc/nginx/sites-available/evolution-api /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Para configurar o SSL/TLS (HTTPS), utilize o Certbot: sudo certbot --nginx -d seu.dominio.com. Este passo é crucial para proteger sua API e garantir a entrega confiável de webhooks. Se seus webhooks ainda falham após essa configuração, a causa pode ser um problema no seu sistema receptor, e você pode consultar Evolution API: Resolvendo Erros de Instância e Webhook para mais detalhes sobre ambos os lados da comunicação.

Perguntas Relacionadas na Evolution API

O que causa o erro ao criar instância Evolution API?

Este erro geralmente ocorre por falha na comunicação com o servidor do WhatsApp, problemas de configuração de rede no seu VPS, ou insuficiência de recursos (RAM/CPU). Verifique os logs do container e do servidor, e certifique-se de que as portas necessárias estão abertas.

Por que a Evolution API perde a conexão com o WhatsApp?

Perda de conexão pode ser causada por instabilidade na rede do seu servidor, reinícios inesperados do serviço de Docker, ou um bloqueio do WhatsApp por atividade suspeita ou excessiva. Monitore a saúde do seu VPS e a utilização de recursos.

Como configurar o webhook para funcionar corretamente?

Garanta que a URL do webhook esteja correta, acessível publicamente e que seu servidor a processe rapidamente. A Evolution API precisa de uma resposta rápida para confirmar que o webhook foi recebido. Verifique também se o `secret` está configurado corretamente em ambos os lados.

Quais são os requisitos de hardware para rodar a Evolution API em produção?

Para produção, recomendamos um VPS com no mínimo 4GB de RAM e 2 vCPUs. Para maior volume de mensagens e estabilidade, 4GB de RAM e 4 vCPUs são ideais, especialmente ao rodar a stack completa com banco de dados e proxy.

Comparativo: MongoDB vs PostgreSQL para Evolution API

A escolha do banco de dados para a Evolution API impacta diretamente na sua confiabilidade e performance, especialmente em cenários de alto volume.

Considerações Finais sobre Banco de Dados

Embora o MongoDB seja o padrão inicial para facilidade de setup, para um ambiente de produção confiável e escalável, o PostgreSQL é a escolha superior. Sua robustez em transações e garantia de integridade de dados são cruciais para evitar perda de mensagens e garantir que a Evolution API funcione sem falhas críticas. A configuração de um banco de dados PostgreSQL externo ao container da API oferece ainda mais resiliência.

Erros Comuns e Como Evitá-los

1. Insuficiência de RAM/CPU: Como mencionado, este é o vilão número um. Use um plano de VPS adequado e monitore o uso de recursos. Para um setup com Evolution API, banco de dados e proxy, 4GB de RAM é o mínimo para produção. Se você está apenas testando, 2GB pode ser suficiente, mas não para produção. Consulte Evolution API: Como Dimensionar CPU e RAM por Volume de Mensagens para um guia mais detalhado.

2. Webhook com URL Incorreta ou Inacessível: Sempre verifique o URL e teste a acessibilidade do seu endpoint de webhook antes de configurar na Evolution API. Use ferramentas como `curl` ou Postman para testar diretamente.

3. Falha na Autenticação do Webhook: Se você configurou um `secret` ou outro método de autenticação, certifique-se de que está idêntico tanto na Evolution API quanto no seu sistema receptor.

4. Logs Obscuros ou Ausentes: Configure o logging detalhado tanto para a Evolution API quanto para os containers Docker. Sem logs claros, diagnosticar problemas se torna uma tarefa árdua.

5. Falha no Banco de Dados: Se o seu banco de dados (MongoDB ou PostgreSQL) não estiver rodando ou acessível, a Evolution API não funcionará. Garanta que o container do banco de dados esteja saudável e que as regras de firewall permitam a comunicação.

Conclusão e Próximos Passos

A manutenção da Evolution API em um ambiente de produção exige atenção à configuração do servidor, à gestão de recursos e à correta implantação dos seus componentes. Ao seguir as práticas recomendadas de deploy com Docker Compose, configurar um proxy reverso e escolher o banco de dados adequado (PostgreSQL para produção), você minimiza significativamente os riscos de instabilidade, desconexões e falhas de webhook.

Entendemos que a infraestrutura correta é a base para qualquer aplicação self-hosted de sucesso. Para garantir que sua Evolution API opere com a máxima performance e confiabilidade, recomendamos a nossa solução:

Implante sua Evolution API em um servidor robusto e confiável com o nosso VPS Brasil Básico por R$ 99/mês. Por apenas R$ 99/mês, você obtém 4GB de RAM e 4 vCPUs, um ambiente perfeito para rodar essa stack completa. Rodamos esse exato setup em uma VPS Brasil Básico, garantindo performance e estabilidade para suas integrações.