Problema / Contexto
Automações de homelab (alertas de monitoramento, relatórios de backup, documentos escaneados) precisam de um canal de entrada/saída acessível via HTTP simples, sem depender de serviço de mensageria externo pago nem da Cloud API oficial da Meta, que exige aprovação de negócio e não serve bem pra uso pessoal/homelab.
Decisões de arquitetura
Self-hosted, não multi-tenant. Um número de WhatsApp, um container Docker, zero serviço externo. Decisão de posicionamento documentada no próprio README: o projeto não visa uso comercial em escala: isso cruzaria de “ferramenta self-hosted” pra “API não-oficial do WhatsApp como serviço”, o que atrai enforcement da Meta.
Protocolo via Baileys, não Cloud API oficial. Uso do protocolo WhatsApp Web via biblioteca reverse-engineered (Baileys), o que exige tratar pareamento (QR code), rate-limiting e fila de envio como responsabilidades de primeira classe do próprio serviço.
Segurança de webhook desde o design. HMAC-SHA256 assinando toda notificação de saída, allow-list de IP/CIDR e rate limiting por IP; não é webhook “aberto” recebendo de qualquer origem.
Fluxo técnico
- 01
Enviar
API HTTP simples pra texto, mídia e documentos, com fila de envio e pacing configurável pra não estourar rate-limit do WhatsApp.
- Fastify
- Fila
- Rate limiting
- 02
Receber
Imagens e documentos de grupos allow-listed são repassados via webhook multipart/form-data.
- Webhook
- multipart/form-data
- Allow-list
- 03
Rastrear
Status de entrega (sent/delivered/read) via webhook, mais métricas Prometheus nativas expostas pelo próprio serviço.
- Prometheus
- Observabilidade
- 04
Operar
Web UI própria com login: pareamento por QR code, diretório de grupos com autocomplete, console de envio e logs com filtro.
- Web UI
- QR Pairing
- 05
Segurança
Webhooks assinados com HMAC-SHA256, allow-list de IP/CIDR e rate limiting por IP.
- HMAC-SHA256
- Allow-list
- Rate limiting
Stack
- runtimeNode 24 · Fastify 5
- protocoloBaileys (WhatsApp Web)
- empacotamentoDocker · multi-arch · non-root · healthcheck
- cibuild automatizado + badge
- observabilityPrometheus (métricas nativas)
Resultado / uso real
MIT license, CI configurado com badge no README, imagem Docker multi-arch non-root com healthcheck. Em uso ativo (não é prova de conceito) como canal de entrada/saída de automações reais dentro do próprio homelab (workflows n8n), incluindo conciliação financeira de uma operação real via integração com maquininha de cartão/PIX.