~/thalespm.me
← back
case studyOpen Source / Backend

WA Courier: self-hosted WhatsApp gateway

Open source HTTP gateway for WhatsApp: one number, one Docker container, zero external service. In production, MIT licensed.

MIT
License
Automated build + badge
CI
Multi-arch, non-root, with healthcheck
Docker image
Actively used (production, not a PoC)
Status

Problem / Context

Homelab automations (monitoring alerts, backup reports, scanned documents) need an entry/exit channel reachable via plain HTTP, without depending on a paid external messaging service or Meta’s official Cloud API, which requires business approval and doesn’t fit personal/homelab use well.

Architecture decisions

Self-hosted, not multi-tenant. One WhatsApp number, one Docker container, zero external service. Positioning decision documented in the project’s own README: it’s not aimed at commercial use at scale: that would cross the line from “self-hosted tool” to “unofficial WhatsApp API as a service”, which draws Meta enforcement.

Baileys protocol, not the official Cloud API. Uses the WhatsApp Web protocol via a reverse-engineered library (Baileys), which means pairing (QR code), rate-limiting and send queueing have to be first-class responsibilities of the service itself.

Webhook security by design. HMAC-SHA256 signs every outgoing notification, plus IP/CIDR allow-listing and per-IP rate limiting; not an “open” webhook accepting from any origin.

Technical flow

  1. 01

    Send

    Simple HTTP API for text, media and documents, with a send queue and configurable pacing to avoid hitting WhatsApp's rate limit.

    • Fastify
    • Queue
    • Rate limiting
  2. 02

    Receive

    Images and documents from allow-listed groups are forwarded via multipart/form-data webhook.

    • Webhook
    • multipart/form-data
    • Allow-list
  3. 03

    Track

    Delivery status (sent/delivered/read) via webhook, plus native Prometheus metrics exposed by the service itself.

    • Prometheus
    • Observability
  4. 04

    Operate

    Own web UI with login: QR code pairing, group directory with autocomplete, send console and filterable logs.

    • Web UI
    • QR Pairing
  5. 05

    Security

    Webhooks signed with HMAC-SHA256, IP/CIDR allow-listing and per-IP rate limiting.

    • HMAC-SHA256
    • Allow-list
    • Rate limiting

Stack

Result / real-world use

MIT licensed, CI configured with a README badge, multi-arch non-root Docker image with healthcheck. Actively used (not a proof of concept) as the entry/exit channel for real automations inside the homelab itself (n8n workflows), including financial reconciliation for a real operation integrated with a card/PIX payment terminal.