Hub independente de WhatsApp: por que tirei tudo do ERP
Painel próprio, API REST, banco PostgreSQL e runtime de workers. A arquitetura que resolveu minhas quedas noturnas e o que ela cobra em troca.
Deu uma sexta-feira em que eu subi uma atualização do sistema às sete da noite e derrubei o WhatsApp de três empresas ao mesmo tempo. Nenhuma delas tinha relação com o que eu mudei. Elas caíram porque a sessão morava dentro do mesmo processo. Foi essa noite que me convenceu a montar um hub independente de WhatsApp.
Antes disso, eu defendia o contrário. Achava que separar era complicar sem necessidade, mais uma coisa para manter, mais um lugar para dar errado. Confesso que demorei pra entender que o custo de manter separado é fixo e previsível, enquanto o custo de manter junto aparece sempre no pior momento.
A separação existe de verdade: o hub vive fora do ERP e é a referência atual para atendimento de WhatsApp independente. Ele tem painel operacional próprio, API REST própria, banco PostgreSQL próprio e runtime Node com Baileys em modo fleet.
O que um hub independente de WhatsApp assume
A divisão de responsabilidades é o que dá tranquilidade. Cada lado tem um papel bem delimitado e nenhum dos dois precisa saber os detalhes internos do outro.
| Lado | Responsabilidade | Como conversa |
|---|---|---|
| ERP | Sincronizar tenants e conexões | Chamadas de API |
| ERP | Pedir envio e consultar estado | Chamadas de API |
| ERP | Receber eventos do canal | Webhook assinado |
| Hub | Autenticar cada ERP cliente | Identificador e segredo de cliente |
| Hub | Persistir clientes, empresas, conexões e workers | Banco próprio |
| Hub | Provisionar worker e atualizar estado | Runtime supervisionado |
Repare que o ERP nunca fala com o WhatsApp diretamente. Ele fala com o hub. Essa camada a mais é exatamente o que impede que um deploy do sistema principal derrube uma sessão, que era o meu problema daquela sexta.
Onde os dados moram
O hub tem banco próprio, e as tabelas contam a história do que ele faz. Tem cadastro de ERPs clientes com credenciais e rotas, empresas por ERP, sessões vinculadas ao tenant, workers com host, porta, identificação de processo e heartbeat, auditoria de runtime e envio, fila interna de tentativas e histórico de entrega de webhook.
- Clientes: os ERPs que consomem o hub, com credencial e rota de retorno.
- Tenants: as empresas de cada ERP, isoladas entre si.
- Conexões: as sessões de WhatsApp vinculadas a cada tenant.
- Workers: host, porta, processo e heartbeat de cada sessão em execução.
- Eventos e tentativas: auditoria de runtime, envio e entrega de webhook.
O histórico de tentativas de webhook foi o que mais me ajudou no primeiro mês. Quando alguém dizia "o cliente mandou mensagem e não chegou", eu parava de discutir e ia olhar a tentativa de entrega. A discussão acabava em dois minutos.
Um worker por sessão, e o gerente da frota
O runtime funciona com um gerente de frota que roda numa porta de controle e cuida dos processos: listar sessões, descobrir a próxima porta livre, criar worker, encerrar worker, reiniciar um ou todos e executar panic. A supervisão dos processos é feita por gerenciador dedicado.
Cada worker roda uma sessão, expõe sua própria API HTTP numa porta dinâmica, conecta ao WhatsApp, gera QR Code, envia mensagem, normaliza os eventos que chegam e reporta tudo de volta ao hub. Uma sessão problemática deixa de contaminar as outras, que era o meu pesadelo.
Como eu faria a migração hoje
- Levante o inventárioListe todas as conexões existentes, de quais empresas e quem depende de cada uma.
- Suba o hub em paraleloDeixe o hub de pé e testado antes de mover qualquer sessão de produção.
- Configure credencial e retornoRegistre o ERP como cliente, defina o segredo de webhook e a rota que vai receber os eventos.
- Migre uma conexão sóEscolha a de menor volume, migre, e observe por alguns dias inteiros antes de continuar.
- Valide envio e retornoTeste cada tipo de mensagem e confirme que os eventos chegam com assinatura válida.
- Migre o resto em lotesNunca tudo de uma vez. Eu tentei e voltei atrás no meio da tarde.
Antes de considerar concluído
- Cada empresa enxerga apenas as próprias conexões, sem vazamento entre tenants.
- O segredo de webhook está configurado e a assinatura está sendo validada.
- O painel do hub foi apresentado a quem cuida do canal no dia a dia.
- Restart de uma sessão foi testado e não afetou as demais.
- O histórico de tentativas de entrega foi consultado ao menos uma vez.
- Existe um caminho de volta documentado, caso algo dê errado.
A conta de manter junto não vem no fim do mês. Vem numa sexta às sete da noite, no meio de um deploy.
Equipe Webajato
O que ler antes de decidir
Se você ainda não escolheu o conector, o comparativo entre Baileys e Meta Cloud API muda de peso quando o hub entra na conta. A parte de assinatura dos eventos está em webhook assinado com HMAC, e o acompanhamento do dia a dia em saúde da conexão WhatsApp. Se você cuida de várias empresas no mesmo ambiente, o isolamento por empresa descrito em gestão multiempresa segue a mesma lógica que o hub aplica aos tenants.