Este guia sobe o n8n e a Evolution API na mesma VPS Ubuntu 24.04. Os dois ficam numa rede interna do Docker Compose. Só o Caddy publica porta, com HTTPS. A Evolution API entrega o evento do WhatsApp no webhook do n8n, e o n8n chama de volta o endpoint de texto da API.

O teste foi feito em 19/11/2026 no Ubuntu 24.04, com Docker Engine 29.10.0 e Compose v5.8.0. As imagens estavam fixadas: n8n e runner 2.48.6, Evolution API v2.3.7, PostgreSQL 18.7 e 15.20, Redis 7.4.12 e Caddy 2.11.9. Não havia um domínio público, então o certificado foi o interno do Caddy. A seção do domínio diz a linha que sai quando o nome é de verdade. O celular não foi pareado: o QR chegou a ser gerado, os eventos qrcode.updated e connection.update entraram no n8n, e o envio de texto respondeu o erro de instância ainda não conectada.

Se o n8n ou a Evolution API já estão no ar em pastas separadas, os guias Como instalar o n8n com Docker numa VPS e Como instalar a Evolution API em uma VPS continuam valendo. Este aqui junta os dois atrás do mesmo proxy.

O que você vai precisar

  • Uma VPS com Ubuntu 24.04 de 64 bits e SSH com um usuário que tenha sudo.
  • Dois nomes em que você consiga criar registros DNS, quando for usar certificado público. Os exemplos são n8n.example.com e api.example.com.
  • Um e-mail para a conta ACME, no dia em que o certificado deixar de ser interno.

São sete contêineres: Caddy, n8n, runner, PostgreSQL do n8n, Evolution API, PostgreSQL da API e Redis. O guia do n8n sozinho trata 2 vCPU e 4 GB como piso, e o da Evolution API pede o mesmo para a API com banco e cache. Juntos, trate 4 vCPU e 8 GB como o piso apertado. O cartão ao lado aponta um plano acima disso. Some o que mais for rodar na mesma máquina antes de escolher.

O Docker, se ainda não estiver instalado, segue o repositório apt oficial. O passo a passo testado está em Como instalar o n8n com Docker numa VPS.

Os dois endereços

O n8n escuta 5678 só na rede do Compose. A Evolution API escuta 8080 na mesma rede. Quem fala com a internet é o Caddy, nas portas 80 e 443.

Isso separa duas URLs que não são a mesma coisa:

  • A URL que o editor do n8n mostra, https://n8n.example.com/webhook/whatsapp, é a pública. Um serviço fora da VPS usa essa.
  • A URL que a Evolution API, no mesmo Compose, chama é http://n8n:5678/webhook/whatsapp. O nome n8n é o serviço. O tráfego não sai para a internet e não depende de o certificado público já existir.

O caminho, whatsapp, tem de ser o mesmo nos dois lados. O que muda é o host.

O Docker passa por cima do ufw. Só o Caddy publica porta. O n8n, a API e os bancos ficam sem ports:. O motivo e o teste estão em A porta do Docker continua aberta com o ufw.

Os arquivos

Crie a pasta. O nome dela vira prefixo dos volumes:

mkdir -p ~/whatsapp && cd ~/whatsapp 

Segredos

Gere a chave de criptografia do n8n e o token do runner com 32 bytes, e as senhas e a chave da API com 16:

openssl rand -hex 32 openssl rand -hex 16 

Rode o primeiro comando duas vezes e o segundo, três: senha do Postgres do n8n, senha do Postgres da Evolution API e AUTHENTICATION_API_KEY. Não reutilize o exemplo 429683C4C977415CAAFCCE10F7D57E11 que vem no .env.example da Evolution API.

N8N_VERSION=2.48.6 N8N_DOMAIN=n8n.example.com EVOLUTION_DOMAIN=api.example.com ACME_EMAIL=voce@example.com GENERIC_TIMEZONE=America/Sao_Paulo N8N_ENCRYPTION_KEY=cole-a-chave-de-32-bytes N8N_RUNNERS_AUTH_TOKEN=cole-o-token-de-32-bytes N8N_POSTGRES_USER=n8n N8N_POSTGRES_PASSWORD=cole-a-senha-do-n8n N8N_POSTGRES_DB=n8n SERVER_URL=https://api.example.com AUTHENTICATION_API_KEY=cole-a-chave-da-api DATABASE_PROVIDER=postgresql DATABASE_CONNECTION_URI=postgresql://evolution:cole-a-senha-da-api@evolution-postgres:5432/evolution_db?schema=evolution_api DATABASE_CONNECTION_CLIENT_NAME=evolution CACHE_REDIS_ENABLED=true CACHE_REDIS_URI=redis://evolution-redis:6379/6 CACHE_REDIS_PREFIX_KEY=evolution TELEMETRY_ENABLED=false LOG_LEVEL=ERROR,WARN,INFO,LOG,WEBHOOKS LANGUAGE=en POSTGRES_DATABASE=evolution_db POSTGRES_USERNAME=evolution POSTGRES_PASSWORD=cole-a-senha-da-api 
chmod 600 .env 

A senha dentro de DATABASE_CONNECTION_URI e a de POSTGRES_PASSWORD são a mesma. Se ela tiver @, :, / ou #, troque esses caracteres pelo código percentual na URI. N8N_VERSION fixa o n8n e o runner, que precisam da mesma versão. 2.48.6 era a stable em 19/11/2026 nas releases do n8n. A tag da Evolution API é a v2.3.7, que é a versão do package.json do repositório e a tag publicada no lugar de latest.

SERVER_URL, AUTHENTICATION_API_KEY, DATABASE_PROVIDER, DATABASE_CONNECTION_URI, CACHE_REDIS_ENABLED e CACHE_REDIS_URI estão no .env.example atual. TELEMETRY_ENABLED=false desliga o envio que o exemplo deixa ligado.

Guarde o .env fora da VPS. O n8n não lê credencial restaurada sem N8N_ENCRYPTION_KEY. A Evolution API não autentica chamada sem AUTHENTICATION_API_KEY.

Caddyfile

O laboratório não tinha domínio público. O local_certs faz o Caddy emitir um certificado da autoridade interna dele para os dois nomes. Foi esse arquivo que subiu:

{ email {$ACME_EMAIL} local_certs } {$N8N_DOMAIN} { reverse_proxy n8n:5678 { flush_interval -1 } } {$EVOLUTION_DOMAIN} { reverse_proxy evolution-api:8080 } 

O flush_interval -1 é o do exemplo de Caddy do n8n: desliga o buffer da resposta. O reverse_proxy manda X-Forwarded-For, X-Forwarded-Proto e X-Forwarded-Host.

Com um domínio público, apague a linha local_certs e deixe o restante. O caddy validate aceitou esse arquivo sem o local_certs. O Caddy então pede o certificado público sozinho, desde que os dois nomes apontem para o IPv4 da VPS e as portas 80 e 443 estejam alcançáveis. O certificado interno deste teste vale poucas horas e o emissor é Caddy Local Authority. Não use esse certificado no lugar do público.

Compose

services: caddy: image: caddy:2.11.9 restart: unless-stopped ports: - "80:80" - "443:443" - "443:443/udp" environment: - N8N_DOMAIN=${N8N_DOMAIN} - EVOLUTION_DOMAIN=${EVOLUTION_DOMAIN} - ACME_EMAIL=${ACME_EMAIL} volumes: - ./Caddyfile:/etc/caddy/Caddyfile:ro - caddy_data:/data - caddy_config:/config depends_on: - n8n - evolution-api n8n-postgres: image: postgres:18.7 restart: always environment: - POSTGRES_USER=${N8N_POSTGRES_USER} - POSTGRES_PASSWORD=${N8N_POSTGRES_PASSWORD} - POSTGRES_DB=${N8N_POSTGRES_DB} - PGDATA=/var/lib/postgresql/data volumes: - n8n_db:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -h localhost -U ${N8N_POSTGRES_USER} -d ${N8N_POSTGRES_DB}"] interval: 5s timeout: 5s retries: 10 n8n: image: docker.n8n.io/n8nio/n8n:${N8N_VERSION} restart: always environment: - N8N_HOST=${N8N_DOMAIN} - N8N_PORT=5678 - N8N_PROTOCOL=https - N8N_WEBHOOK_URL=https://${N8N_DOMAIN}/ - N8N_PROXY_HOPS=1 - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY} - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true - GENERIC_TIMEZONE=${GENERIC_TIMEZONE} - TZ=${GENERIC_TIMEZONE} - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=n8n-postgres - DB_POSTGRESDB_PORT=5432 - DB_POSTGRESDB_DATABASE=${N8N_POSTGRES_DB} - DB_POSTGRESDB_USER=${N8N_POSTGRES_USER} - DB_POSTGRESDB_PASSWORD=${N8N_POSTGRES_PASSWORD} - N8N_RUNNERS_MODE=external - N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN} - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0 volumes: - n8n_data:/home/node/.n8n depends_on: n8n-postgres: condition: service_healthy n8n-runner: image: n8nio/runners:${N8N_VERSION} restart: always environment: - N8N_RUNNERS_AUTH_TOKEN=${N8N_RUNNERS_AUTH_TOKEN} - N8N_RUNNERS_TASK_BROKER_URI=http://n8n:5679 depends_on: - n8n evolution-api: image: evoapicloud/evolution-api:v2.3.7 restart: always env_file: - .env volumes: - evolution_instances:/evolution/instances depends_on: - evolution-redis - evolution-postgres evolution-redis: image: redis:7.4.12 restart: always command: redis-server --port 6379 --appendonly yes volumes: - evolution_redis:/data networks: default: aliases: - evolution-redis evolution-postgres: image: postgres:15.20 restart: always environment: POSTGRES_DB: ${POSTGRES_DATABASE} POSTGRES_USER: ${POSTGRES_USERNAME} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} command: ["postgres", "-c", "max_connections=1000"] volumes: - evolution_postgres:/var/lib/postgresql/data volumes: caddy_data: caddy_config: n8n_db: n8n_data: evolution_instances: evolution_redis: evolution_postgres: 

O que esse arquivo faz, e o que o teste viu:

  • N8N_WEBHOOK_URL é a URL base do webhook desde o n8n 2.30.0. Sem ela, o editor monta http://localhost:5678/. N8N_PROXY_HOPS=1 faz o n8n confiar no único proxy da frente. O guia O webhook do n8n mostra localhost:5678 mede as duas variáveis.
  • O runner externo é o modo que a documentação do n8n recomenda em produção. A imagem n8nio/runners:2.48.6 usa a mesma versão do n8n.
  • PGDATA=/var/lib/postgresql/data no Postgres 18.7 mantém o banco dentro do volume. Não apague essa linha.
  • A Evolution API usa o docker-compose.yaml oficial como base e larga a rede dokploy-network, que não existe numa VPS nova. A imagem deixa de ser latest e passa a ser v2.3.7. O Postgres fica em 15.20 e o Redis em 7.4.12, no lugar das tags flutuantes do arquivo oficial.
  • O env_file entrega o .env inteiro para a API. Ela ignora as chaves do n8n. As senhas dos dois Postgres têm nomes diferentes de propósito: um único POSTGRES_PASSWORD no mesmo arquivo seria lido pelos dois serviços.

Subir

cd ~/whatsapp sudo docker compose up -d sudo docker compose ps 

O n8n espera o Postgres ficar saudável. A Evolution API aplica as migrações do Prisma na subida e só então escuta. Acompanhe até as duas linhas:

sudo docker compose logs n8n sudo docker compose logs evolution-api 

No n8n, o fim útil é Editor is now accessible via: seguido de https://n8n.example.com. Na API, HTTP - ON: 8080 e a versão v2.3.7.

O certificado interno fica em caddy/pki/authorities/local/root.crt no volume do Caddy. Para o curl deste laboratório confiar nele:

sudo docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt curl --cacert ./caddy-root.crt -fsS https://n8n.example.com/healthz curl --cacert ./caddy-root.crt -fsS https://api.example.com 

O primeiro responde {"status":"ok"}. O segundo responde JSON com "version":"2.3.7" e "message":"Welcome to the Evolution API, it is working!". Com certificado público, apague o --cacert ./caddy-root.crt.

No laboratório os nomes n8n.example.com e api.example.com apontavam para 127.0.0.1 no /etc/hosts da própria máquina. Na sua VPS, com domínio público, eles apontam para o IPv4 no DNS.

A instância e o webhook

A Evolution API v2.3.7 cria a instância em POST /instance/create. O corpo pede instanceName e integration. WHATSAPP-BAILEYS é a conexão pelo WhatsApp Web. A documentação da API avisa que ela pode ter limitações em relação à API oficial da Meta.

Carregue a chave e crie a instância atendimento:

set -a && . ./.env && set +a curl --cacert ./caddy-root.crt -fsS -X POST https://api.example.com/instance/create \ -H "apikey: $AUTHENTICATION_API_KEY" \ -H "Content-Type: application/json" \ -d '{"instanceName":"atendimento","integration":"WHATSAPP-BAILEYS","qrcode":false}' 

A resposta é 201. Guarde o instanceId. O hash é um token da instância: não cole em chat nem em repositório.

O webhook da versão 2.3.7 não é a lista solta de campos. O corpo tem um objeto webhook, como o schema do repositório exige (enabled e url obrigatórios):

curl --cacert ./caddy-root.crt -fsS -X POST https://api.example.com/webhook/set/atendimento \ -H "apikey: $AUTHENTICATION_API_KEY" \ -H "Content-Type: application/json" \ -d '{"webhook":{"enabled":true,"url":"http://n8n:5678/webhook/whatsapp","byEvents":false,"base64":false,"events":["MESSAGES_UPSERT","QRCODE_UPDATED","CONNECTION_UPDATE"]}}' 

A resposta é 201 e devolve a mesma URL. Confira com:

curl --cacert ./caddy-root.crt -fsS https://api.example.com/webhook/find/atendimento \ -H "apikey: $AUTHENTICATION_API_KEY" 

MESSAGES_UPSERT é o evento de mensagem nova. QRCODE_UPDATED e CONNECTION_UPDATE servem para ver a conexão antes de existir mensagem. byEvents: false manda tudo para a mesma URL. Com true, a API acrescenta o nome do evento no caminho e o n8n deixa de achar o webhook.

O QR, para escanear no celular em Aparelhos conectados:

curl --cacert ./caddy-root.crt -fsS https://api.example.com/instance/connect/atendimento \ -H "apikey: $AUTHENTICATION_API_KEY" 

A resposta traz base64 (a imagem do QR) e count. Neste teste o count chegou a 1 e o log da API registrou qrcode.updated e connection.update com state: connecting, os dois com destino http://n8n:5678/webhook/whatsapp.

O workflow no n8n

Abra https://n8n.example.com, crie a conta de owner e um workflow com dois nós.

  1. Nó Webhook, método POST, caminho whatsapp, resposta imediata. Publique o workflow. A URL de produção fica https://n8n.example.com/webhook/whatsapp.
  2. Nó HTTP Request, método POST, URL http://evolution-api:8080/message/sendText/atendimento. Cabeçalho apikey com o valor de AUTHENTICATION_API_KEY. Corpo JSON com number (DDI e DDD, só dígitos) e text.

Ligue a saída do Webhook na entrada do HTTP Request. Publique de novo. No teste, o painel mostrou esta URL de produção, com Authentication em None:

URL de produção do webhook do n8n em https://n8n.example.com/webhook/whatsapp, no workflow que chama a Evolution API

O workflow publicado num nome público aceita POST de qualquer um. A Evolution API desta stack chama http://n8n:5678 por dentro e não precisa dessa URL pública para entregar o evento. No teste, qrcode.updated e connection.update também executaram o nó HTTP Request e receberam o mesmo 500. Esses eventos não são mensagem: o sendText só faz sentido quando o evento é MESSAGES_UPSERT.

O webhook de produção só existe com o workflow publicado. Antes disso, POST /webhook/whatsapp responde 404 e o corpo diz que o workflow precisa estar ativo.

Um POST de fora, pelo Caddy, confirma o caminho público. Com o workflow publicado:

curl --cacert ./caddy-root.crt -fsS -X POST https://n8n.example.com/webhook/whatsapp \ -H "Content-Type: application/json" \ -d '{"event":"messages.upsert","data":{"message":{"conversation":"oi do teste"}}}' 

A resposta é {"message":"Workflow was started"}. Na execução, o n8n grava webhookUrl como https://n8n.example.com/webhook/whatsapp e x-forwarded-proto como https.

A Evolution API, do contêiner dela, usa a URL interna. No teste, cada qrcode.updated virou uma execução com status success no n8n. É o mesmo webhook. Não é um segundo workflow.

Antes de escanear o QR

Sem o celular pareado, o envio não sai. O comando, nos dois momentos, foi este:

curl --cacert ./caddy-root.crt -sS -o /tmp/send-text.json -w '%{http_code}\n' \ -X POST https://api.example.com/message/sendText/atendimento \ -H "apikey: $AUTHENTICATION_API_KEY" \ -H "Content-Type: application/json" \ -d '{"number":"5511999999999","text":"teste de envio antes do pareamento"}' 

O código foi 500 nas duas vezes. Logo depois do create, antes do connect, a mensagem interna era Cannot read properties of undefined (reading 'onWhatsApp'). Depois do connect, com a instância em connecting, o corpo foi:

{ "status": 500, "error": "Internal Server Error", "response": { "message": "Cannot read properties of undefined (reading 'find')" } } 

O mesmo 500 apareceu na execução do n8n quando o nó HTTP Request chamou http://evolution-api:8080/message/sendText/atendimento. O workflow foi marcado como sucesso porque o nó estava com continuar em caso de erro. O item da execução guardou o texto 500 - "{\"status\":500,...}".

Isso não é uma mensagem entregue no WhatsApp. É a API respondendo antes de existir sessão. Depois que o QR for aceito no celular, o mesmo POST é o envio. Este laboratório parou antes desse aceite: não houve telefone, então não houve mensagem saindo para um número real.

O corpo do sendText na v2.3.7 é o da classe SendTextDto do repositório: number e text. O cabeçalho é apikey, não Authorization.

O que sobrevive a um recomeço

Com a instância e o webhook gravados, reinicie só a API:

sudo docker compose restart evolution-api 

Espere HTTP - ON: 8080 de novo e repita o GET /instance/fetchInstances e o GET /webhook/find/atendimento. No teste, atendimento continuou na lista e a URL do webhook continuou http://n8n:5678/webhook/whatsapp. A sessão do WhatsApp, quando existir, fica no volume evolution_instances.

Recrie o n8n sem apagar o volume:

sudo docker compose up -d --force-recreate n8n 

No teste, o login do owner voltou a responder 200 e urlBaseWebhook continuou https://n8n.example.com/. A conta fica no Postgres 18.7 e a chave, no volume n8n_data.

O backup que este teste gravou:

cd ~/whatsapp set -a && . ./.env && set +a sudo docker compose exec -T n8n-postgres pg_dumpall -U "$N8N_POSTGRES_USER" > n8n-db-$(date +%F).sql grep -c "PostgreSQL database cluster dump complete" n8n-db-$(date +%F).sql sudo docker compose exec -T evolution-postgres pg_dump -U "$POSTGRES_USERNAME" "$POSTGRES_DATABASE" > evolution-$(date +%F).sql grep -c "PostgreSQL database dump complete" evolution-$(date +%F).sql sudo docker run --rm --volumes-from "$(sudo docker compose ps -q n8n)" -v "$PWD":/backup ubuntu:24.04 tar czf /backup/n8n-data-$(date +%F).tar.gz /home/node/.n8n 

Os dois grep imprimiram 1. Copie os .sql, o .tar.gz e o .env para outra máquina. Uma cópia que fica só neste disco se perde com a VPS. O guia do n8n detalha a restauração.

Nunca rode docker compose down -v nesta pasta. O -v apaga os volumes: o banco do n8n, a chave, o banco da Evolution API e as sessões do WhatsApp.

Atualizar

As tags deste guia não flutuam. Atualizar é trocar o número no .env ou no Compose, ler a nota da versão e recriar.

cd ~/whatsapp sudo docker compose pull sudo docker compose up -d 

No teste, o pull das sete imagens pinadas respondeu que já estavam baixadas, e o up -d manteve os contêineres. Trocar N8N_VERSION puxa o n8n e o runner juntos. O n8n aplica migração ao iniciar, e voltar a tag não desfaz a migração: o dump vem antes. A Evolution API v2.3.7 não avisa sozinha quando um salto de versão exige passo manual no banco. Leia a nota no repositório antes de mudar a tag.

Subir o Postgres de 18.7 para outra versão principal, ou o 15.20 da API, é dump e restauração, não troca de tag.

Próximo passo

Publicado originalmente em https://nuvits.net/blog/n8n-evolution-api-mesma-vps