Webhooks do CRM: parei de perguntar ao sistema o tempo todo
Um script rodava de minuto em minuto perguntando se tinha novidade. Quase sempre não tinha. Webhook resolveu isso invertendo a pergunta.
A gente tinha um script que perguntava ao sistema, de minuto em minuto, se havia mensagem nova. Rodava o dia inteiro. Na esmagadora maioria das vezes a resposta era "não". Quando finalmente entendi que os webhooks do CRM invertem essa lógica — o sistema avisa você quando algo acontece —, desliguei o script e ganhei de volta um monte de processamento que não servia para nada.
Webhook tem duas direções e a confusão entre elas custou algumas horas do meu time. Existe o que chega, com evento vindo de fora para dentro do CRM. E existe o que sai, com o CRM avisando um sistema externo. Configuração, risco e diagnóstico são diferentes em cada direção.
Vou separar as duas, mostrar o que cada uma persiste e apontar os lugares onde eu já vi integração quebrar em silêncio. Se você ainda está decidindo entre consultar e ser avisado, o comparativo do outro lado está em API REST do CRM.
O que os webhooks do CRM recebem
Do lado de entrada, existe recepção de webhook de WhatsApp genérico e recepção por tipo de conector, com processamento de payload nos formatos suportados. O evento chega, o sistema resolve a qual conexão ele pertence pelo identificador externo e grava o que veio.
- Persistência de mensagens, com atualização de status.
- Persistência de reações e de citações, que preservam o contexto da conversa.
- Persistência de metadados que acompanham o evento.
- Entrega de arquivo de chat por URL assinada, em vez de link aberto.
- Recepção de webhook de pagamento dos provedores suportados.
- Recepção pública de eventos de marketplace por canal, com registro do payload bruto.
O que o CRM envia para fora
Do lado de saída, você cadastra os webhooks dentro do CRM, testa antes de confiar, exclui quando não fizer mais sentido e acompanha o log de entrega. Existe assinatura HMAC configurável para o que sai, e existe auditoria das tentativas com o resultado de cada uma.
Confesso que o botão de teste foi a funcionalidade que eu mais ignorei no começo, e a que mais me salvou depois. Cadastrar uma URL errada é fácil demais. Descobrir isso três dias depois, porque ninguém recebeu nada e ninguém reclamou, é o tipo de silêncio caro que a integração produz.
| Direção | O que verificar | Onde dói quando falha |
|---|---|---|
| Entrada | Resolução da conexão pelo identificador externo | Mensagem chega e não aparece em conversa nenhuma |
| Entrada | Persistência de status, reação e citação | Histórico incompleto na hora de auditar um atendimento |
| Saída | URL cadastrada e teste executado | Ninguém recebe e ninguém percebe por dias |
| Saída | Assinatura HMAC configurada | O destino não consegue provar que o evento veio de você |
| Saída | Log de entrega e tentativas | Falha intermitente vira mistério sem histórico |
Assinatura: quem prova que o evento é seu
A assinatura HMAC configurável nos webhooks de saída existe para o destino conferir que a mensagem veio mesmo do seu CRM e chegou sem alteração. Sem ela, qualquer um que descubra a URL do parceiro pode mandar um evento falso. Configure e peça para o time do outro lado validar de verdade, e não apenas ignorar o cabeçalho.
Evento sem dono e o risco de isolamento
Quando chega um evento e existem várias contas do mesmo canal, o sistema não associa a empresa por adivinhação. Ele registra e deixa a sincronização a cargo do polling autenticado agendado. Isso é a decisão certa, e cria uma consequência prática: os registros que ficaram sem empresa resolvida precisam de revisão de isolamento antes de qualquer exposição do painel. Não é detalhe de segurança, é o detalhe de segurança.
O critério completo de fronteira entre empresas está em isolamento multiempresa em relatórios. Do lado do marketplace, o contexto de canais e pedidos está em marketplaces e WAHub.
Como eu coloco um webhook novo no ar
- Escreva o evento e o efeito esperadoQual evento dispara, o que o outro sistema faz quando recebe e o que acontece se não receber. Essa última pergunta é a que ninguém faz.
- Cadastre e rode o testeUse o teste antes de qualquer tráfego real. URL com erro de digitação é o defeito mais comum e o mais silencioso.
- Ligue a assinaturaConfigure o HMAC e confirme com o parceiro que a validação está ativa do lado dele, não só documentada.
- Observe o log de entrega por uma semanaProcure falha intermitente. Ela é mais perigosa que falha total, porque ninguém abre chamado.
- Combine o plano de reprocessamentoDefina quem reprocessa e como, quando o destino ficar fora do ar. Combinar isso depois do incidente é tarde.
Webhook e relatório se ajudam
Todo evento persistido vira dado consultável depois. Mensagem, status, reação e metadado alimentam os números que você vai ler no dashboard CRM. Quando um indicador de atendimento fica estranho, a primeira coisa que eu confiro não é o cálculo. É se algum webhook parou de entregar e deixou um buraco na base.
- Existe alguém que percebe quando um webhook para de entregar?
- O log de tentativas está sendo olhado, ou só existe?
- A assinatura de saída está configurada e validada do outro lado?
- Eventos sem empresa resolvida têm tratamento definido?
- Há um caminho de reprocessamento testado, e não apenas planejado?
Por onde eu começaria
Abra o log de entrega dos seus webhooks de saída e olhe os últimos sete dias. Se estiver tudo verde, ótimo, você levou dois minutos. Se tiver falha intermitente que ninguém reportou, você acabou de encontrar um problema que estava crescendo em silêncio. Depois disso, encadeie a rotina agendada descrita em comandos CLI para cobrir o que o evento não cobre.