Security
- Set
APP_BASIC_AUTHwith a long random password. A non-loopback bind requires credentials unlessAPP_ALLOW_UNAUTHENTICATED=trueexplicitly disables that check. Loopback can run without credentials for local development. - Set
WHATSAPP_WEBHOOK_SECRETexplicitly. Without it, GOWA generates a random key that changes on restart. VerifyX-Hub-Signature-256over the raw request body. Keep outbound webhook TLS verification enabled. - Terminate TLS at a reverse proxy; GOWA itself speaks plain HTTP.
- Restrict
/statics. QR codes and downloaded media under/statics/*are served without Basic Auth. Block or protect that path at the proxy if media is sensitive, and prunestatics/mediaregularly. - Do not expose
/chatwoot/webhookwithoutCHATWOOT_WEBHOOK_SECRETwhen Chatwoot is enabled. - Set
APP_CORS_ALLOWED_ORIGINSif browsers call the API directly; wildcard CORS does not authorize browser writes or/ws. Configure specific origins inAPP_TRUSTED_ORIGINSor the CORS allowlist. See Authentication. - Bind privately (
APP_HOST=127.0.0.1or a private network) when only local services need access. - Rate-limit failed logins at the proxy; GOWA has no built-in rate limiting.
Storage and backups
- Use PostgreSQL for
DB_URIif you want managed backups; chat storage is always SQLite. - Back up while GOWA is stopped, or use your database’s online backup tools.
- Store backups encrypted: the session database is equivalent to a logged-in account.
- Run one GOWA instance per storage. Two processes sharing a session cause disconnects and conflicts. GOWA does not support horizontal scaling.
Docker
- Pin a version tag rather than
latest, and read the release notes before upgrading. - The container runs as a non-root user (UID 20001); make sure mounted volumes are writable.
- The image sets
TZ=UTC. Schedules use thetimezoneyou pass, so this does not affect them.
Reverse proxy
- Set
APP_TRUSTED_PROXIESto your proxy’s address range so client IPs are read correctly. - Allow WebSocket upgrades on
/ws. - Raise the body limit to at least 100 MB (
client_max_body_size 100m;in nginx). - Keep proxy timeouts above GOWA’s 45-second request timeout.
- For sub-path deployments use
APP_BASE_PATH;/healthremains at the root.
Monitoring
- Liveness:
GET /healthreturns200 OKwhen the process and store are up. It does not check WhatsApp. - WhatsApp connectivity: poll
GET /devices/{device_id}/statusand alert whenis_logged_inisfalse. - Events: subscribe to webhooks and alert on missing traffic for busy numbers.
- Logs: collect container stdout; use
APP_DEBUG=trueonly while troubleshooting.
GET /app/metrics returns authenticated process, memory, disk, and device metrics without selecting a device. See Server metrics. Alert on device.logged_out, device.temporary_ban, and device.reachout_timelock webhooks.
Webhook receivers
- Respond
2xxwithin 10 seconds; process work asynchronously. - Deduplicate by device, event type, and the event’s identifiers. Message IDs alone do not distinguish edits, reactions, or later receipt states.
- After 5 failed attempts the event is dropped. Use
GET /chatsandGET /chat/{jid}/messagesto catch up after an outage.
Sending hygiene
- Message people who opted in or wrote first.
- Pace sends with delays and jitter; avoid identical bulk text.
- Stop on
WA_REACHOUT_TIMELOCK. - Keep
WHATSAPP_ACCOUNT_VALIDATION=trueso unregistered numbers fail fast. - WhatsApp allows up to four linked companion devices per account, and unlinks companions after about 14 days if the phone stays offline.
