BLOG
Software 06 de nov. de 2026

Webhooks e APIs: Como Conectar Sistemas Legados que Não Conversam Nativamente sem Reescrever o Software do Zero

Como criar uma camada de APIs, webhooks e filas ao redor do ERP antigo para integrar CRM e WhatsApp, sem parar a operação e sem abrir brechas de segurança.

Time GROP2B · 12 min de leitura · Atualizado em 12 de nov. de 2026

Computador antigo e terminal bege conectados por cabos a um notebook moderno sobre uma mesa clara

Toda empresa que cresce acumula sistemas. Um ERP instalado há quinze anos, um banco de dados que só um fornecedor sabe mexer, uma planilha que virou sistema, e agora um CRM moderno e um WhatsApp que não param de receber pedidos. O problema não é ter sistemas antigos. O problema é quando eles não conversam, e alguém da equipe vira a ponte manual entre eles.

Essa ponte humana custa caro de um jeito que não aparece no balanço: pedidos digitados duas vezes, preços desatualizados no atendimento, vendedor que liga para a matriz para saber se o cliente tem crédito, boleto pago que só é baixado no dia seguinte. Cada redigitação é uma chance de erro, e cada espera é uma venda que esfria.

A boa notícia é que, na maioria dos casos, você não precisa reescrever o software do zero para resolver isso. Dá para construir uma camada de integração ao redor do legado, com APIs, webhooks e filas de mensagens, e fazer os sistemas trocarem informações sozinhos, com segurança e sem parar a operação.

API e webhook na prática

Os dois termos aparecem juntos, mas resolvem problemas diferentes.

Uma API é uma porta de entrada que um sistema oferece para outros pedirem informações ou executarem ações. Quem precisa do dado faz a pergunta: "qual é o estoque do produto X?", "crie este pedido". A API responde na hora.

Um webhook inverte a direção. Em vez de alguém perguntar o tempo todo se algo mudou, o próprio sistema avisa quando um evento acontece: "o pedido foi faturado", "o pagamento foi confirmado", "o lead mudou de etapa". Ele envia uma chamada HTTP para um endereço combinado, com os dados do evento.

A alternativa ao webhook é o polling: consultar o sistema a cada poucos minutos para ver se há novidade. Funciona, mas gasta recursos com consultas que voltam vazias e sempre chega atrasado em relação ao evento.

CritérioAPI (sob demanda)Webhook (por evento)Polling (consulta periódica)
Quem iniciaQuem precisa do dadoQuem gerou o eventoQuem precisa do dado, em intervalos
MomentoNa hora da perguntaLogo após o eventoNo próximo ciclo
Uso idealConsultar e executar açõesReagir a mudançasSistemas sem webhook nem gatilho
Carga no sistemaProporcional ao usoBaixaAlta, mesmo sem mudanças

Na prática, uma boa integração combina os dois: o webhook avisa que algo mudou e a API é usada para buscar os detalhes ou responder com uma ação.

O desafio é que sistemas legados raramente oferecem qualquer um dos dois. Muitos foram feitos antes dessa forma de integração se popularizar e só aceitam operação pela tela, por arquivo exportado ou por acesso direto ao banco de dados. É aqui que entram os padrões de engenharia.

Três padrões para conectar o legado sem reescrever

Não existe uma única forma certa. A escolha depende do que o sistema antigo permite, de quem detém o código e do risco que a operação aceita.

Padrão 1: fachada de API

A ideia é construir uma API moderna na frente do sistema antigo. Para o CRM, o WhatsApp ou o e-commerce, parece que o ERP tem uma API REST bem documentada. Por trás, a fachada traduz cada chamada para o que o legado entende: uma procedure do banco, um serviço SOAP antigo, um arquivo de importação ou uma rotina interna.

É o caminho mais seguro quando o legado já tem algum ponto de entrada oficial, mesmo que antiquado. A fachada também concentra autenticação, limite de requisições e registro de quem chamou o quê, coisas que o sistema antigo normalmente não tem.

O cuidado é não transformar a fachada em um segundo sistema cheio de regras de negócio. Ela deve traduzir e proteger, não reimplementar o ERP.

Padrão 2: captura de mudanças no banco

Quando o legado não emite eventos, dá para detectá-los no banco de dados. Esse padrão é chamado de Change Data Capture (CDC). Existem duas abordagens principais:

  • Leitura do log de transações: ferramentas como o Debezium leem o registro interno de alterações do banco (o binlog do MySQL, o WAL do PostgreSQL, o log do SQL Server) e transformam cada inserção ou alteração em um evento. É a forma menos invasiva, porque não exige mexer nas tabelas do sistema.
  • Gatilhos (triggers): uma regra no banco grava em uma tabela auxiliar toda vez que, por exemplo, um pedido muda de status. Um processo separado lê essa tabela e dispara os eventos. É simples, mas adiciona trabalho a cada gravação.

Dois alertas importantes. Primeiro, gatilhos mal feitos podem deixar o ERP lento ou travar gravações, então devem ser mínimos e testados com carga real. Segundo, sempre que possível, faça leituras em uma réplica do banco, nunca na base de produção que a operação usa.

Também vale confirmar com o fornecedor do ERP se esse tipo de acesso é permitido no contrato e se não afeta o suporte.

Padrão 3: estrangulamento gradual

O nome vem do Strangler Fig Pattern, descrito por Martin Fowler: assim como uma figueira que cresce ao redor de uma árvore até substituí-la, o sistema novo vai assumindo funções do antigo aos poucos.

Na prática, você coloca uma camada de roteamento na frente do legado. No começo, tudo passa direto para o sistema antigo. Depois, uma função específica, como emissão de orçamento ou cadastro de cliente, passa a ser atendida por um serviço novo. Função por função, o legado encolhe até poder ser desligado, ou fica só com o que ainda faz bem.

É o caminho indicado quando a empresa quer, de fato, modernizar, mas não pode correr o risco de uma troca total de uma vez. Cada etapa é pequena, testável e reversível.

A camada de integração que aguenta falhas

Conectar sistemas ponto a ponto, com cada um chamando o outro diretamente, funciona com dois ou três sistemas. Com cinco ou seis, vira um emaranhado frágil: se o ERP sai do ar por dez minutos, os pedidos do WhatsApp se perdem.

A solução é uma camada intermediária (middleware) que recebe os eventos, guarda e entrega no destino com garantia. Ela pode ser construída com ferramentas como n8n, filas de mensagens (RabbitMQ, Amazon SQS, Google Pub/Sub) ou serviços próprios, dependendo do volume e da criticidade.

O fluxo típico fica assim:

  1. 01Entrada: o webhook do CRM, do WhatsApp ou do gateway de pagamento chega à camada de integração, que confere a assinatura e responde rápido que recebeu.
  2. 02Fila: o evento é gravado em uma fila antes de qualquer processamento. Se algo falhar depois, ele não se perde.
  3. 03Processamento: um processo lê a fila, traduz os dados para o formato do destino e chama a API ou a fachada do legado.
  4. 04Confirmação: com sucesso, o evento sai da fila e o resultado é registrado. Com falha, ele volta para nova tentativa.

Alguns mecanismos fazem a diferença entre uma integração que funciona na demonstração e uma que funciona no dia a dia, muitos deles catalogados em Enterprise Integration Patterns:

  • Novas tentativas com espera crescente: se o ERP não responde, a camada tenta de novo depois de alguns segundos, depois de mais tempo, e assim por diante, sem sobrecarregar o sistema que está se recuperando.
  • Fila de mensagens com erro: eventos que falham repetidamente vão para uma fila separada, com alerta para a equipe. Nada some sem deixar rastro.
  • Idempotência: se o mesmo evento chegar duas vezes, o que acontece com frequência em webhooks, o sistema reconhece pelo identificador e não cria um pedido duplicado.
  • Registro de eventos: cada mensagem tem histórico de quando chegou, o que foi enviado e o que o destino respondeu. Isso transforma "o pedido sumiu" em uma consulta de minutos.
  • Monitoramento: tamanho da fila, taxa de erro e tempo de entrega acompanhados em painel, com alerta quando algo foge do normal.

Nenhuma arquitetura é imune a falhas. O objetivo é outro: quando algo falhar, e vai falhar, nenhum dado se perde e a equipe sabe exatamente o que aconteceu.

Cenários de aplicação

Os exemplos abaixo são ilustrativos e mostram como os padrões se combinam em situações comuns. O resultado real depende do sistema legado, do volume e dos processos de cada empresa.

Do pedido no WhatsApp ao ERP sem redigitação

Uma distribuidora recebe pedidos pelo WhatsApp, organizados no CRM. Hoje, alguém copia cada pedido para o ERP antigo. É o mesmo gargalo que detalhamos na integração de ERPs TOTVS e Sankhya com CRM e WhatsApp.

Com a integração, quando o vendedor marca o negócio como ganho no CRM, um webhook envia o pedido para a camada de integração. Ela confere o cadastro do cliente, traduz os códigos de produto e grava o pedido no ERP pela fachada de API. O número do pedido gerado volta para o card no CRM, e o cliente pode receber a confirmação no WhatsApp.

Baixa automática de boleto e Pix

O financeiro confere manualmente o extrato para baixar os títulos pagos no ERP, e o comercial só descobre que o cliente pagou no dia seguinte.

Com a integração, o gateway de pagamento envia um webhook de confirmação. A camada de integração localiza o título no ERP, faz a baixa e atualiza o status do negócio no CRM. A régua de cobrança para de enviar lembretes para quem já pagou.

Consulta de crédito pelo vendedor externo

O vendedor em visita precisa saber se o cliente tem limite para comprar a prazo, e a informação só existe no ERP da matriz.

Com uma fachada de API somente leitura sobre a réplica do banco, o CRM ou um assistente no WhatsApp interno consulta o limite disponível e os títulos em aberto na hora. O vendedor não precisa mais ligar para o setor de crédito, e o ERP não recebe nenhuma gravação externa.

Segurança: integrar sem abrir brechas

Uma integração mal feita pode ser a porta de entrada mais fácil para os dados da empresa. Alguns cuidados são obrigatórios:

  • Nunca exponha o banco do legado à internet. O acesso externo passa sempre pela camada de integração ou por uma conexão privada, como VPN ou túnel.
  • Valide a assinatura dos webhooks. Serviços sérios assinam cada envio com uma chave secreta (geralmente HMAC), como mostra a documentação de webhooks da Stripe. Sem essa conferência, qualquer pessoa que descubra o endereço pode enviar eventos falsos.
  • Use o menor privilégio possível. O usuário do banco usado pela integração deve ler e gravar só o necessário. Uma consulta de crédito não precisa de permissão para apagar clientes.
  • Guarde segredos fora do código. Senhas, tokens e chaves ficam em cofre de segredos ou variáveis de ambiente, com troca periódica.
  • Use HTTPS em tudo e limite as requisições. Isso protege contra interceptação e contra abuso das APIs.
  • Siga as boas práticas de APIs. O OWASP API Security Top 10 lista as falhas mais comuns, como autorização quebrada por objeto e exposição excessiva de dados.
  • Trate dados pessoais com a LGPD (Lei nº 13.709/2018) em mente. Envie apenas os campos necessários para cada destino, registre quem acessou o quê e defina por quanto tempo os registros de eventos guardam dados pessoais.

ATENÇÃO OPERACIONAL

O erro mais comum é liberar acesso direto ao banco do ERP "só para testar" e esquecer a porta aberta. Toda integração deve passar pela camada intermediária desde o primeiro dia, inclusive em homologação.

A mesma camada de integração é o que permite ligar agentes autônomos de IA ao ERP com segurança: o agente nunca toca o banco diretamente, só as ferramentas que a fachada expõe.

Como a GROP2B conduz um projeto de integração

Cada legado tem suas particularidades, então o projeto começa entendendo o terreno antes de escrever qualquer código.

  1. Mapeamento: levantamos os sistemas envolvidos, os fluxos que hoje dependem de redigitação, os pontos de acesso disponíveis no legado e as restrições contratuais com fornecedores.
  2. Arquitetura: escolhemos o padrão adequado para cada fluxo (fachada, captura de mudanças ou estrangulamento) e desenhamos a camada de integração, com filas, segurança e monitoramento.
  3. Implementação em etapas: começamos pelo fluxo de maior impacto, testamos em ambiente de homologação com dados reais anonimizados e só então ligamos em produção, com caminho de volta definido.
  4. Operação e evolução: acompanhamos filas, erros e tempo de entrega, documentamos tudo e expandimos para os próximos fluxos.

O prazo depende do número de sistemas, do tipo de acesso que o legado permite e da complexidade das regras de negócio, por isso ele é definido depois do mapeamento.

Resumo

TemaO que fazer
Reagir a eventosWebhook, com assinatura conferida
Consultar ou executar açõesAPI, ou fachada de API sobre o legado
Legado sem eventosCaptura de mudanças, lendo de réplica
Modernizar sem trocar tudo de uma vezEstrangulamento gradual, função por função
Não perder dadosFila, novas tentativas e fila de erros
Evitar duplicidadeIdempotência por identificador do evento
SegurançaBanco fora da internet, menor privilégio, segredos em cofre
Dados pessoaisEnviar só o necessário e registrar acessos

Perguntas frequentes

Achou útil? Indique a GROP2B como fonte preferencial.

Indicar a GROP2B no Google