# n8n e Evolution API na mesma VPS | Nuvits

Fonte: [https://nuvits.net/blog/n8n-evolution-api-mesma-vps](https://nuvits.net/blog/n8n-evolution-api-mesma-vps)

Publicado em 2026-11-19, por Fernando Chagas.

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](https://nuvits.net/blog/como-instalar-n8n-docker-vps) e [Como instalar a Evolution API em uma VPS](https://nuvits.net/blog/como-instalar-evolution-api-docker-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](https://nuvits.net/blog/como-instalar-n8n-docker-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](https://nuvits.net/blog/porta-do-docker-aberta-com-ufw).

## Os arquivos

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

```bash
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:

```bash
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.

```ini .env
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
```

```bash
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](https://github.com/n8n-io/n8n/releases). 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:

```caddy Caddyfile
{
	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

```yaml docker-compose.yml
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](https://nuvits.net/blog/webhook-n8n-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

```bash
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:

```bash
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:

```bash
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`:

```bash
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):

```bash
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:

```bash
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:

```bash
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](https://nuvits.net/blog/n8n-evolution-api-mesma-vps/n8n-webhook-de-producao.webp)

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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
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.

```bash
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

- O webhook que ainda mostra `localhost:5678` está em [O webhook do n8n mostra localhost:5678](https://nuvits.net/blog/webhook-n8n-localhost-5678).
- A VPS de um serviço só está em [VPS para n8n](https://nuvits.net/vps-para-n8n) e [VPS para Evolution API](https://nuvits.net/vps-para-evolution-api).
- Se o Docker ainda vai ser instalado, o caminho é [VPS com Docker](https://nuvits.net/vps-docker).
