---
title: "Deploy Evolution API Webhook"
description: "Receive WhatsApp events in your app by webhook"
category: "Bots"
url: https://railway.com/deploy/deploy-evolution-api-whatsapp-webhooks
---

# Deploy Evolution API Webhook

Receive WhatsApp events in your app by webhook

**[Deploy Evolution API Webhook on Railway](https://railway.com/template/deploy-evolution-api-whatsapp-webhooks)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-evolution-api-whatsapp-webhooks/manifest.json

- **Creator:** onepush
- **Category:** Bots

## Template content

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### evolution-api

- **Image:** evoapicloud/evolution-api:v2.3.7@sha256:1bd8afc4a6cf48822e6cf02469aeae7bd35a12a6b616eacd1291926307f4d339
- **Health check:** /
- **Public domain:** Yes

## Documentation

# Deploy and Host self hosted Evolution API Webhook (Open-Source WhatsApp API) on Railway

Deploys Evolution API v2.3.7 with Postgres and Redis so your backend receives WhatsApp events by webhook. For developers building support bots or n8n workflows.

## About Hosting Evolution API Webhook open-source software on Railway (self hosted Evolution API template)

This template runs the official Evolution API image with Postgres and Redis, so your session files, instance settings, and webhook URLs stay inside your Railway project. No third-party SaaS touches your events, and each instance keeps its own webhook config.

Railway handles the boring parts: it provisions the database and cache, wires the connection strings, publishes a public domain, and restarts the container after a crash. You still own the Baileys session risk, but the infrastructure is repeatable and yours.

## Why Deploy Evolution API Webhook, the Twilio alternative on Railway (Railway Free Trial)

Evolution API Webhook gives you Twilio-style WhatsApp events without Twilio's per-message markup, and you keep the payloads inside your own Railway network.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Evolution API Webhook on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

### Railway vs Other Hosting Providers and VPS for Evolution API Webhook self hosting

Here's how Railway stacks up against common VPS options for running Evolution API and its webhook receiver.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | Managed Postgres, Redis, volume, public URL | You install Docker, Postgres, Redis, SSL, public IP |
| AWS | Private network for your webhook receiver | You manage VPCs, security groups, load balancers |
| Hetzner | Session files persist on Railway volume | You manage volume, backups, uptime |

## Common Use Cases for hosted Evolution API Webhook

- **Support bot inbox:** Read MESSAGES_UPSERT to push every inbound WhatsApp text into your ticket queue, filter `fromMe` so you don't loop your own replies.
- **CRM chat log:** Append each MESSAGES_UPSERT and MESSAGES_UPDATE to the contact's timeline for a searchable history.
- **Disconnect alerts:** Watch CONNECTION_UPDATE and page a human when the linked phone drops, before customers notice.
- **n8n workflow trigger:** Point the instance webhook at an n8n Webhook node to run automations on new messages.
- **Delivery receipts:** Use MESSAGES_UPDATE for sent order confirmations to mark orders as delivered or read.

## Dependencies for Evolution API Webhook Docker hosted on Railway

Evolution API webhooks need three Railway services: the API container, Postgres, and Redis. Postgres stores instances, messages, contacts and chats, Redis is the cache, and WhatsApp session files live on the /evolution/instances volume.

### Deployment Dependencies for Managed Evolution API Webhook Service (WhatsApp API)

- **evolution-api:** evoapicloud/evolution-api:v2.3.7, port 8080, health /, volume /evolution/instances. Public.
- **Postgres:** DATABASE_URL maps to DATABASE_CONNECTION_URI; saves data with DATABASE_SAVE flags true.
- **Redis:** REDIS_URL maps to CACHE_REDIS_URI.
- **Generated config:** AUTHENTICATION_API_KEY is a 32-character global key sent as apikey and used to log into /manager. SERVER_URL is your Railway domain. TELEMETRY_ENABLED=false.

### Implementation Details for Evolution API Webhook (Using Evolution API official docker image)

Open /manager with the global API key, create an instance, and scan the QR code. WEBHOOK_GLOBAL_WEBHOOK_BY_EVENTS appends the event name to the URL. Keep default retries with exponential backoff. The root URL returns a welcome JSON with the version.

## How does Evolution API Webhook compare against other WhatsApp API platforms

### Evolution API vs Twilio (Twilio Alternative)

- **Pricing:** Evolution API is free open source, so you pay only hosting. Twilio adds per-message fees on top of Meta's.
- **Connection and webhooks:** Evolution API supports free Baileys or official Cloud API, with per-instance webhooks and event filtering. Twilio uses only the official Cloud API.
- **Twilio wins:** Fully managed compliance, scaling, and uptime.

### Evolution API vs WAHA (WAHA Alternative)

- **Cost and license:** Evolution API is free under an Apache-2.0 based license. WAHA has a paid Plus edition for some features.
- **Transports and integrations:** Evolution API offers webhooks, WebSocket, RabbitMQ, and SQS, plus Typebot, Chatwoot, Dify, n8n and more built in.
- **WAHA wins:** Simpler setup for small projects.

### Evolution API vs WhatsApp Cloud API (WhatsApp Cloud API Alternative)

- **Official status:** Direct Cloud API is Meta-official. Evolution API on Baileys is unofficial with ban risk, though you can connect it to Cloud API.
- **Setup and webhooks:** Direct Cloud API needs business verification and templates. Evolution API with Baileys scans a QR code and gives per-instance event filtering and status events.
- **Cloud API wins:** Better deliverability and compliance at business scale.

### Evolution API vs Z-API (Z-API Alternative)

- **Cost:** Z-API charges monthly per instance. Evolution API is free; you pay only your own hosting.
- **Hosting and features:** Z-API is a managed SaaS. Evolution API is self-hosted with more integrations, transports, and webhook options.
- **Z-API wins:** No infrastructure to manage.

## How to use Evolution API Webhook (the OSS WhatsApp API)?

1. Open https://your-domain/manager and log in with the generated AUTHENTICATION_API_KEY.
2. Create an instance, open its QR code, and scan it from WhatsApp on your phone under Linked devices.
3. Deploy a small HTTP receiver, or add an n8n Webhook node, and copy its public URL.
4. In the manager, open the instance, go to Events, then Webhook, and set the URL with MESSAGES_UPSERT and CONNECTION_UPDATE enabled, or call /webhook/set/your-instance with the apikey header.
5. Send a test WhatsApp message to the number linked to that instance.
6. Watch your receiver logs: you should get a MESSAGES_UPSERT event with the text and sender. If you don't, check the current setting with:

```bash
curl -H "apikey: YOUR_GLOBAL_KEY" https://your-domain/webhook/find/your-instance
```

7. Reply programmatically with POST /message/sendText/your-instance, passing your apikey header and the message fields in the request body.

## How to self host Evolution API Webhook on other VPS Services (Evolution API self hosting guide)

### Clone the Repository

`git clone https://github.com/EvolutionAPI/evolution-api` then `cd evolution-api`. The repo includes a `docker-compose.yml` for the full stack.

### Install Dependencies

`cp .env.example .env`. Only Docker and Compose are required. The official image bundles Node.js and TypeScript.

### Configure Environment Variables

Set `AUTHENTICATION_API_KEY`, `DATABASE_PROVIDER=postgresql`, `DATABASE_CONNECTION_URI`, `CACHE_REDIS_URI`. For webhooks, `WEBHOOK_GLOBAL_ENABLED`, `WEBHOOK_GLOBAL_URL`. Use a strong random value for the API key. Retries are tuned with WEBHOOK_RETRY_MAX_ATTEMPTS, WEBHOOK_RETRY_INITIAL_DELAY_SECONDS and WEBHOOK_RETRY_MAX_DELAY_SECONDS.

### Start the Evolution API Webhook Application

`docker compose up -d`. Log into `https://your-domain/manager`, create an instance, and set its webhook. Check logs with `docker compose logs -f`.

## Official Pricing of Evolution API Webhook (Evolution API pricing)

Evolution API Webhook is open source and free to use: there's no license fee, no per-instance charge, and no cost for webhook delivery itself. Twilio-style markups don't apply unless you also use Twilio.

## Evolution API Webhook cloud vs self hosted comparison (Pricing, features, costs, and more)

Self-hosting gives you the same webhook engine without per-message fees, but you own the phone session and the server.

### Monthly cost of self hosting Evolution API Webhook on Railway

On Railway, expect roughly 5-15 USD/month for the API service plus Postgres and Redis at light use, after the 5 USD trial. That is the whole cost for the open-source version.

### System Requirements for Hosting Evolution API Webhook on a VPS

Evolution API does not publish strict minimums. A Docker host with 1 vCPU, 1GB RAM, and 10GB disk comfortably runs the API, Postgres, and Redis for a single instance. Add more RAM if you keep many sessions or enable aggressive message logging.

## Frequently Asked Questions (FAQs)

### Instance webhook vs global webhook: which one should I use?

Use per-instance webhooks unless every instance hits the same backend. Global env vars like WEBHOOK_GLOBAL_URL apply to all instances.

### Why do I receive my own outgoing messages?

MESSAGES_UPSERT fires for sent messages too. Check the fromMe flag and ignore or route those entries.

### How many times does Evolution API retry a failed webhook?

Up to 10 times by default, with exponential backoff capped at 300 seconds. Status codes 400, 401, 403, 404, and 422 are not retried.

### Can n8n receive Evolution API webhooks?

Yes, point an n8n Webhook node URL at the instance webhook setting, or run n8n as another Railway service and call it over the private network. Return 2xx quickly.

### Why did events stop after my phone disconnected?

CONNECTION_UPDATE tells you the session dropped; if you only subscribed to MESSAGES_UPSERT, a disconnect produces no message events. Subscribe to CONNECTION_UPDATE and re-scan the QR code.

### Can I use WebSocket or RabbitMQ instead of webhooks?

Yes, Evolution API supports WebSocket, RabbitMQ, and SQS. Use them when you want a persistent connection or a queue instead of a public URL.


## Similar templates

- [Swarm](https://railway.com/deploy/swarm) — Named LLM bots join channels, take jobs, run routines on your Railway box
- [Telegram JavaScript Bot](https://railway.com/deploy/5lRkWa) — A template for Telegram bot in JavaScript using grammY
- [Cobalt Tools [Updated Oct ’26]](https://railway.com/deploy/cobalt) — Cobalt Tools [Oct ’26] (Media Downloader, Converter & Automation) Self Host

Open this page in a browser: https://railway.com/deploy/deploy-evolution-api-whatsapp-webhooks