n8n e Evolution API na mesma VPS
Contexto e versões testadas
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 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.
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 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 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. Nó Webhook, método POST, caminho whatsapp, resposta imediata. Publique o workflow. A URL de produção fica https://n8n.example.com/webhook/whatsapp.
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:
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.upser
Comments
No comments yet. Start the discussion.