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.
Neste artigo
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.comeapi.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 nomen8né 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.
Os arquivos
Crie a pasta. O nome dela vira prefixo dos volumes:
mkdir -p ~/whatsapp && cd ~/whatsappSegredos
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 16Rode 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
[email protected]
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-apichmod 600 .envA 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.
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 montahttp://localhost:5678/.N8N_PROXY_HOPS=1faz 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.6usa a mesma versão do n8n. PGDATA=/var/lib/postgresql/datano Postgres 18.7 mantém o banco dentro do volume. Não apague essa linha.- A Evolution API usa o
docker-compose.yamloficial como base e larga a rededokploy-network, que não existe numa VPS nova. A imagem deixa de serlateste passa a serv2.3.7. O Postgres fica em15.20e o Redis em7.4.12, no lugar das tags flutuantes do arquivo oficial. - O
env_fileentrega o.envinteiro para a API. Ela ignora as chaves do n8n. As senhas dos dois Postgres têm nomes diferentes de propósito: um únicoPOSTGRES_PASSWORDno mesmo arquivo seria lido pelos dois serviços.
Subir
cd ~/whatsapp
sudo docker compose up -d
sudo docker compose psO 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-apiNo 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.comO 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.
- Nó Webhook, método POST, caminho
whatsapp, resposta imediata. Publique o workflow. A URL de produção ficahttps://n8n.example.com/webhook/whatsapp. - Nó HTTP Request, método POST, URL
http://evolution-api:8080/message/sendText/atendimento. Cabeçalhoapikeycom o valor deAUTHENTICATION_API_KEY. Corpo JSON comnumber(DDI e DDD, só dígitos) etext.
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:

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-apiEspere 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 n8nNo 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/.n8nOs 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.
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 -dNo 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
- O webhook que ainda mostra
localhost:5678está em O webhook do n8n mostra localhost:5678. - A VPS de um serviço só está em VPS para n8n e VPS para Evolution API.
- Se o Docker ainda vai ser instalado, o caminho é VPS com Docker.