Skip to main content

Security

  • Set APP_BASIC_AUTH with a long random password. A non-loopback bind requires credentials unless APP_ALLOW_UNAUTHENTICATED=true explicitly disables that check. Loopback can run without credentials for local development.
  • Set WHATSAPP_WEBHOOK_SECRET explicitly. Without it, GOWA generates a random key that changes on restart. Verify X-Hub-Signature-256 over 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 prune statics/media regularly.
  • Do not expose /chatwoot/webhook without CHATWOOT_WEBHOOK_SECRET when Chatwoot is enabled.
  • Set APP_CORS_ALLOWED_ORIGINS if browsers call the API directly; wildcard CORS does not authorize browser writes or /ws. Configure specific origins in APP_TRUSTED_ORIGINS or the CORS allowlist. See Authentication.
  • Bind privately (APP_HOST=127.0.0.1 or 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_URI if 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 the timezone you pass, so this does not affect them.

Reverse proxy

  • Set APP_TRUSTED_PROXIES to 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; /health remains at the root.
See Installation for an nginx example.

Monitoring

  • Liveness: GET /health returns 200 OK when the process and store are up. It does not check WhatsApp.
  • WhatsApp connectivity: poll GET /devices/{device_id}/status and alert when is_logged_in is false.
  • Events: subscribe to webhooks and alert on missing traffic for busy numbers.
  • Logs: collect container stdout; use APP_DEBUG=true only while troubleshooting.
GOWA reconnects automatically on startup and checks connections every 5 minutes. A device logged out from the phone must be paired again. 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 2xx within 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 /chats and GET /chat/{jid}/messages to 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=true so 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.