DEV Community

Fernando Chagas for Nuvits

Posted on Edited on Originally published at nuvits.net

n8n and Evolution API on the same VPS

This guide runs n8n and Evolution API on the same Ubuntu 24.04 VPS. Both stay on the internal Docker Compose network. Only Caddy publishes a port, with HTTPS. Evolution API delivers the WhatsApp event to n8n's webhook, and n8n calls the API's text endpoint back.

The test ran on 19 November 2026 on Ubuntu 24.04, with Docker Engine 29.10.0 and Compose v5.8.0. The images were pinned: n8n and the runner at 2.48.6, Evolution API at v2.3.7, PostgreSQL at 18.7 and 15.20, Redis at 7.4.12 and Caddy at 2.11.9. There was no public domain, so the certificate was Caddy's internal one. The domain section names the line you remove when the name is real. No phone was paired: a QR code was generated, the qrcode.updated and connection.update events reached n8n, and sending a text returned the error of an instance that is not connected yet.

If n8n or Evolution API is already running in its own directory, How to install n8n with Docker on a VPS and How to install Evolution API on a VPS still apply. This guide puts the two of them behind one proxy.

What you need

  • An Ubuntu 24.04 64-bit VPS and SSH as a user with sudo.
  • Two names where you can create DNS records, once you want a public certificate. The examples are n8n.example.com and api.example.com.
  • An email address for the ACME account, on the day the certificate stops being internal.

There are seven containers: Caddy, n8n, the runner, n8n's PostgreSQL, Evolution API, the API's PostgreSQL and Redis. The n8n guide on its own treats 2 vCPU and 4 GB as the floor, and the Evolution API guide asks for the same for the API with its database and cache. Together, treat 4 vCPU and 8 GB as a tight floor. The card beside this article points at a plan above that. Add up whatever else will run on the machine before you choose.

If Docker is not installed yet, use Docker's official apt repository. The tested steps are in How to install n8n with Docker on a VPS.

The two addresses

n8n listens on 5678 only on the Compose network. Evolution API listens on 8080 on the same network. Caddy is what talks to the internet, on ports 80 and 443.

That splits two URLs that are not the same thing:

  • The URL the n8n editor shows, https://n8n.example.com/webhook/whatsapp, is the public one. A service outside the VPS uses it.
  • The URL Evolution API calls from the same Compose project is http://n8n:5678/webhook/whatsapp. The name n8n is the service. The traffic does not leave the host and does not depend on a public certificate already existing.

The path, whatsapp, has to match on both sides. The host is what changes.

Docker bypasses ufw. Only Caddy publishes a port. n8n, the API and the databases have no ports:. The reason and the test are in Docker's published port stays open with ufw.

The files

Create the directory. Its name becomes the volume prefix:

mkdir -p ~/whatsapp && cd ~/whatsapp
Enter fullscreen mode Exit fullscreen mode

Secrets

Generate n8n's encryption key and the runner token with 32 bytes, and the passwords and the API key with 16:

openssl rand -hex 32
openssl rand -hex 16
Enter fullscreen mode Exit fullscreen mode

Run the first command twice. Run the second three times: the n8n Postgres password, the Evolution API Postgres password and AUTHENTICATION_API_KEY. Do not reuse the sample 429683C4C977415CAAFCCE10F7D57E11 that ships in Evolution API's .env.example.

N8N_VERSION=2.48.6
N8N_DOMAIN=n8n.example.com
EVOLUTION_DOMAIN=api.example.com
ACME_EMAIL=you@example.com
GENERIC_TIMEZONE=America/Sao_Paulo

N8N_ENCRYPTION_KEY=paste-the-32-byte-key
N8N_RUNNERS_AUTH_TOKEN=paste-the-32-byte-token
N8N_POSTGRES_USER=n8n
N8N_POSTGRES_PASSWORD=paste-the-n8n-password
N8N_POSTGRES_DB=n8n

SERVER_URL=https://api.example.com
AUTHENTICATION_API_KEY=paste-the-api-key
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:paste-the-api-password@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=paste-the-api-password
Enter fullscreen mode Exit fullscreen mode
chmod 600 .env
Enter fullscreen mode Exit fullscreen mode

The password inside DATABASE_CONNECTION_URI and POSTGRES_PASSWORD are the same one. If it contains @, :, / or #, percent-encode those characters in the URI. N8N_VERSION pins n8n and the runner, which have to be the same version. 2.48.6 was the stable release on 19 November 2026 on n8n's releases. The Evolution API tag is v2.3.7, which is the version in the repository package.json and the published tag in place of latest. Set GENERIC_TIMEZONE to your IANA time zone if it is not São Paulo. The lab used America/Sao_Paulo.

SERVER_URL, AUTHENTICATION_API_KEY, DATABASE_PROVIDER, DATABASE_CONNECTION_URI, CACHE_REDIS_ENABLED and CACHE_REDIS_URI are in the current .env.example. TELEMETRY_ENABLED=false turns off the reporting the sample leaves on.

Keep a copy of .env off the VPS. n8n cannot read a restored credential without N8N_ENCRYPTION_KEY. Evolution API will not authenticate a call without AUTHENTICATION_API_KEY.

Caddyfile

The lab had no public domain. local_certs makes Caddy issue a certificate from its internal authority for both names. This is the file that actually started:

{
    email {$ACME_EMAIL}
    local_certs
}

{$N8N_DOMAIN} {
    reverse_proxy n8n:5678 {
        flush_interval -1
    }
}

{$EVOLUTION_DOMAIN} {
    reverse_proxy evolution-api:8080
}
Enter fullscreen mode Exit fullscreen mode

flush_interval -1 comes from n8n's Caddy example: it turns off response buffering. reverse_proxy sends X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host.

With a public domain, delete the local_certs line and leave the rest. caddy validate accepted that file without local_certs. Caddy then requests the public certificate on its own, as long as both names point at the VPS IPv4 and ports 80 and 443 are reachable. The internal certificate from this test lasts a few hours and the issuer is Caddy Local Authority. Do not use it in place of the public certificate.

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:
Enter fullscreen mode Exit fullscreen mode

What this file does, and what the test saw:

  • N8N_WEBHOOK_URL is the webhook base URL from n8n 2.30.0 on. Without it, the editor builds http://localhost:5678/. N8N_PROXY_HOPS=1 makes n8n trust the single proxy in front. The n8n webhook shows localhost:5678 measures both variables.
  • The external runner is the mode the n8n docs recommend for production. The image n8nio/runners:2.48.6 uses the same version as n8n.
  • PGDATA=/var/lib/postgresql/data on Postgres 18.7 keeps the database inside the volume. Do not delete that line.
  • Evolution API starts from the official docker-compose.yaml and drops the dokploy-network, which does not exist on a new VPS. The image is v2.3.7 instead of latest. Postgres is 15.20 and Redis is 7.4.12, instead of the floating tags in the official file.
  • env_file hands the whole .env to the API. It ignores n8n's keys. The two Postgres passwords have different names on purpose: a single POSTGRES_PASSWORD in the same file would be read by both services.

Start

cd ~/whatsapp
sudo docker compose up -d
sudo docker compose ps
Enter fullscreen mode Exit fullscreen mode

n8n waits until Postgres is healthy. Evolution API applies the Prisma migrations on startup and only then listens. Follow the logs until these two lines:

sudo docker compose logs n8n
sudo docker compose logs evolution-api
Enter fullscreen mode Exit fullscreen mode

For n8n, the useful ending is Editor is now accessible via: followed by https://n8n.example.com. For the API, HTTP - ON: 8080 and version v2.3.7.

The internal certificate lives at caddy/pki/authorities/local/root.crt in Caddy's volume. For this lab's curl to trust it:

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
Enter fullscreen mode Exit fullscreen mode

The first answers {"status":"ok"}. The second answers JSON with "version":"2.3.7" and "message":"Welcome to the Evolution API, it is working!". With a public certificate, drop --cacert ./caddy-root.crt.

In the lab, n8n.example.com and api.example.com pointed at 127.0.0.1 in the machine's own /etc/hosts. On your VPS, with a public domain, they point at the IPv4 address in DNS.

The instance and the webhook

Evolution API v2.3.7 creates the instance at POST /instance/create. The body requires instanceName and integration. WHATSAPP-BAILEYS is the WhatsApp Web connection. The API's own documentation warns that it can have limitations compared with Meta's official API.

Load the key and create the atendimento instance:

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}'
Enter fullscreen mode Exit fullscreen mode

The response is 201. Keep the instanceId. The hash is an instance token: do not paste it into a chat or a repository.

The v2.3.7 webhook is not a flat list of fields. The body has a webhook object, which is what the repository schema requires (enabled and url are mandatory):

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"]}}'
Enter fullscreen mode Exit fullscreen mode

The response is 201 and returns the same URL. Check it with:

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

MESSAGES_UPSERT is the new-message event. QRCODE_UPDATED and CONNECTION_UPDATE show the connection before any message exists. byEvents: false sends everything to the same URL. With true, the API appends the event name to the path and n8n no longer finds the webhook.

The QR code, to scan on the phone under Linked devices:

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

The response carries base64 (the QR image) and count. In this test count reached 1 and the API log recorded qrcode.updated and connection.update with state: connecting, both aimed at http://n8n:5678/webhook/whatsapp.

The workflow in n8n

Open https://n8n.example.com, create the owner account and a workflow with two nodes.

  1. A Webhook node, POST method, path whatsapp, immediate response. Publish the workflow. The production URL becomes https://n8n.example.com/webhook/whatsapp.
  2. An HTTP Request node, POST method, URL http://evolution-api:8080/message/sendText/atendimento. An apikey header with the value of AUTHENTICATION_API_KEY. A JSON body with number (country code and area code, digits only) and text.

Connect the Webhook output to the HTTP Request input. Publish again. In the test, the panel showed this production URL, with Authentication set to None:

n8n production webhook URL https://n8n.example.com/webhook/whatsapp on the workflow that calls Evolution API

A workflow published on a public name accepts a POST from anyone. Evolution API in this stack calls http://n8n:5678 from inside and does not need that public URL to deliver the event. In the test, qrcode.updated and connection.update also ran the HTTP Request node and got the same 500. Those events are not messages: sendText only makes sense when the event is MESSAGES_UPSERT.

The production webhook exists only while the workflow is published. Before that, POST /webhook/whatsapp answers 404 and the body says the workflow has to be active.

A POST from outside, through Caddy, confirms the public path. With the workflow published:

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"}}}'
Enter fullscreen mode Exit fullscreen mode

The response is {"message":"Workflow was started"}. In the execution, n8n records webhookUrl as https://n8n.example.com/webhook/whatsapp and x-forwarded-proto as https.

Evolution API, from its own container, uses the internal URL. In the test, each qrcode.updated became an execution with status success in n8n. It is the same webhook. It is not a second workflow.

Before you scan the QR code

Without the phone paired, the send does not leave. The command, at both moments, was this:

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"}'
Enter fullscreen mode Exit fullscreen mode

The status was 500 both times. Right after create, before connect, the inner message was Cannot read properties of undefined (reading 'onWhatsApp'). After connect, with the instance at connecting, the body was:

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

The same 500 showed up in the n8n execution when the HTTP Request node called http://evolution-api:8080/message/sendText/atendimento. The workflow was marked successful because the node was set to continue on error. The execution item stored the text 500 - "{\"status\":500,...}".

That is not a message delivered on WhatsApp. It is the API answering before a session exists. After the phone accepts the QR code, the same POST is the send. This lab stopped before that acceptance: there was no phone, so no message left for a real number.

The sendText body on v2.3.7 is the repository's SendTextDto: number and text. The header is apikey, not Authorization.

What survives a restart

With the instance and the webhook stored, restart only the API:

sudo docker compose restart evolution-api
Enter fullscreen mode Exit fullscreen mode

Wait for HTTP - ON: 8080 again and repeat GET /instance/fetchInstances and GET /webhook/find/atendimento. In the test, atendimento was still in the list and the webhook URL was still http://n8n:5678/webhook/whatsapp. The WhatsApp session, once it exists, lives in the evolution_instances volume.

Recreate n8n without deleting the volume:

sudo docker compose up -d --force-recreate n8n
Enter fullscreen mode Exit fullscreen mode

In the test, the owner login answered 200 again and urlBaseWebhook was still https://n8n.example.com/. The account lives in Postgres 18.7 and the key lives in the n8n_data volume.

The backup this test wrote:

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
Enter fullscreen mode Exit fullscreen mode

Both grep commands printed 1. Copy the .sql files, the .tar.gz and .env to another machine. A copy that stays only on this disk is lost with the VPS. The n8n guide walks through the restore.

Never run docker compose down -v in this directory. -v deletes the volumes: n8n's database, the key, Evolution API's database and the WhatsApp sessions.

Update

The tags in this guide do not float. Updating means changing the number in .env or in Compose, reading the release note and recreating.

cd ~/whatsapp
sudo docker compose pull
sudo docker compose up -d
Enter fullscreen mode Exit fullscreen mode

In the test, pull of the seven pinned images reported they were already downloaded, and up -d left the containers in place. Changing N8N_VERSION pulls n8n and the runner together. n8n applies migrations on startup, and switching the tag back does not undo a migration: the dump comes first. Evolution API v2.3.7 does not tell you on its own when a version jump needs a manual database step. Read the note in the repository before you change the tag.

Moving Postgres off 18.7 to another major version, or the API's 15.20, is a dump and restore, not a tag change.

Next step


Originally published at https://nuvits.net/en/blog/n8n-evolution-api-same-vps

Top comments (0)