API, webhook ou plataforma de integração: qual escolher

Webhook é um aviso automático que um sistema manda para outro quando algo acontece: o pagamento foi aprovado, o pedido foi criado, o cliente respondeu no WhatsApp. API é o caminho contrário, a porta que um sistema deixa aberta para outros perguntarem coisas e pedirem ações. Plataforma de integração é um serviço pronto que liga os dois lados com pouco ou nenhum código.

A escolha entre eles não é questão de gosto. Depende do que o sistema de origem oferece, do volume de dados, de quanta regra de negócio existe no meio do caminho e de quem vai manter a integração funcionando daqui a dois anos. Serve para quem precisa tomar essa decisão, ou conversar com quem vai implementar, sem ser programador.

O que é API, explicado sem jargão

API (sigla em inglês para interface de programação de aplicações) é um conjunto de endereços e regras que um sistema publica para outros programas conversarem com ele. Cada endereço, chamado endpoint, faz uma coisa: consultar pedidos, criar um cliente, baixar uma nota.

A analogia mais próxima é o telefone da transportadora. Você liga, se identifica, pergunta se a encomenda 4471 já saiu e recebe a resposta. Pode ligar quantas vezes quiser, mas só fica sabendo de algo quando pergunta. Na API é igual: seu sistema faz uma requisição, autenticada com uma chave ou token, e o outro sistema devolve a resposta, geralmente em JSON, um formato de texto estruturado que qualquer linguagem de programação entende.

O problema aparece quando você precisa saber de algo assim que acontece. Com API pura, o único jeito é perguntar de tempos em tempos, o que se chama polling. Perguntar a cada minuto se entrou pedido novo gasta chamadas (quase toda API limita quantas você pode fazer por minuto ou por dia), sobrecarrega os dois lados e ainda deixa um atraso de até um minuto.

O que é webhook e como ele funciona

Webhook é a transportadora mandando mensagem quando a encomenda sai, sem você perguntar. Tecnicamente, é uma requisição HTTP do tipo POST que o sistema de origem envia para um endereço seu, cadastrado antes, sempre que acontece um evento que você assinou.

O conteúdo dessa requisição, chamado payload, costuma ser um JSON parecido com este:

{
  "id": "evt_7c21f09a",
  "tipo": "pedido.pago",
  "criado_em": "2026-09-30T14:32:10-03:00",
  "dados": {
    "pedido": "10482",
    "cliente": { "nome": "Marina Souza", "email": "marina@exemplo.com.br" },
    "itens": [
      { "sku": "CAN-500-AZ", "quantidade": 2, "preco": 149.95 }
    ],
    "frete": 90.00,
    "total": 389.90
  }
}

Três campos merecem atenção. O id identifica o evento e é o que permite descartar repetições. O tipo diz o que aconteceu, e é por ele que seu sistema decide o que fazer. O criado_em registra quando o evento foi gerado, o que nem sempre coincide com a ordem de chegada.

Alguns fornecedores mandam o evento completo, como no exemplo. Outros mandam só o aviso e o identificador ("o pedido 10482 mudou"), e o detalhe você busca pela API. O segundo modelo dá um pouco mais de trabalho, mas garante que você sempre lê a versão mais recente do dado.

O webhook resolve o atraso e o desperdício do polling, mas traz uma obrigação nova: seu endereço precisa estar no ar, com HTTPS, pronto para receber a qualquer hora. E, por ser público, qualquer pessoa que descubra esse endereço pode mandar dados falsos para ele. A seção de segurança, mais abaixo, trata disso.

API vs webhook: diferenças na prática

Nas integrações que funcionam bem, as duas trabalham juntas. O webhook avisa que o pedido foi pago; a integração usa a API para buscar o pedido completo e confirmar o status; e, uma vez por dia, uma rotina lista pela API os pedidos das últimas 24 horas e confere se algum aviso se perdeu. Esse desenho aparece com mais detalhe no texto sobre como fazer ERP, CRM e planilhas conversarem.

Nem todo sistema oferece webhook. ERPs mais antigos costumam ter só API, ou nem isso. Já a plataforma oficial do WhatsApp Business entrega mensagens recebidas e status de envio por webhook, e é por isso que qualquer automação de WhatsApp para empresas começa por um endereço preparado para receber esses avisos.

Plataforma de integração ou integração sob medida

Plataforma de integração, também chamada de iPaaS (sigla em inglês para plataforma de integração como serviço), é um serviço na nuvem com conectores prontos para os sistemas mais usados. Você monta o fluxo encaixando blocos: quando chegar um lead no formulário, crie um contato no CRM e avise o canal da equipe. Zapier, Make, n8n e Power Automate são exemplos conhecidos da categoria, com modelos de cobrança e recursos diferentes entre si.

Integração sob medida é código escrito para o seu caso, rodando num servidor ou serviço de nuvem da empresa, com a fila, os registros e as regras que a operação precisa.

A plataforma é a escolha certa quando os dois sistemas têm conector pronto, o fluxo tem poucas regras, o volume é moderado e quem vai manter não é desenvolvedor. Também serve para validar um processo antes de investir em código.

A integração sob medida compensa quando:

• o volume é alto e a cobrança por execução passa a pesar mais do que a hospedagem;
• a regra de negócio tem muitas exceções (tabela de preço por cliente, conversão de unidade, regra fiscal);
• um dos lados é um sistema legado sem conector;
• os dados são sensíveis e a empresa não quer que fiquem no histórico de terceiros;
• a operação precisa de fila de reprocessamento e alerta sob controle próprio.

Existe o caminho do meio: plataforma para os fluxos simples, código para os críticos. O que não funciona é deixar um fluxo crítico, como a entrada de pedidos no ERP, dependendo da conta pessoal de um funcionário numa plataforma que só ele sabe mexer. É a mesma conta de sistema sob medida ou software pronto, em escala menor.

Como proteger um webhook: assinatura, segredo, idempotência e reenvio

O endereço que recebe o webhook é público. Sem proteção, qualquer um que descubra a URL pode mandar um "pedido pago" falso e disparar uma expedição. Estes cuidados são o mínimo para um webhook em produção.

Assinatura com segredo compartilhado. Ao cadastrar o webhook, fica definido um segredo que só o fornecedor e você conhecem. A cada envio, o fornecedor calcula uma assinatura a partir do conteúdo e do segredo (normalmente HMAC com SHA-256, uma espécie de lacre) e manda no cabeçalho da requisição. Seu sistema recalcula com o mesmo segredo e compara; se não bater, descarta. A documentação do GitHub sobre validação de entregas de webhook mostra o processo e um detalhe que costuma passar batido: a comparação deve ser feita em tempo constante, com função própria para isso, e não com a comparação de texto comum da linguagem.

Corpo bruto. A assinatura é calculada sobre o conteúdo exatamente como chegou. Se o framework interpretar e reformatar o JSON antes da verificação, a assinatura deixa de bater. Guarde o corpo original para validar.

Segredo fora do código. O segredo fica em variável de ambiente ou cofre de senhas, nunca no repositório, e é trocado periodicamente ou quando houver suspeita de vazamento.

Proteção contra repetição. Quem intercepta uma requisição válida pode reenviá-la depois. Por isso alguns fornecedores incluem um carimbo de horário dentro do conteúdo assinado, e o receptor recusa eventos antigos demais. As bibliotecas da Stripe, por exemplo, usam tolerância padrão de cinco minutos.

Idempotência. O mesmo evento pode chegar mais de uma vez, por reenvio legítimo. Grave o id de cada evento processado e ignore o que já foi visto. Sem isso, um reenvio vira pedido duplicado no ERP.

Responder rápido e processar depois. O receptor confirma o recebimento (código HTTP 200) em poucos segundos e deixa o processamento pesado para uma fila. Se demorar, o fornecedor entende como falha e reenvia.

Reenvio e ordem. Quando seu endereço falha, fornecedores maduros tentam de novo por um tempo. Na documentação de webhooks da Stripe, as novas tentativas em produção seguem por até três dias, com intervalos crescentes, e a própria documentação avisa que a ordem de entrega dos eventos não é garantida. Seu sistema não pode assumir que "pedido criado" chega antes de "pedido pago".

Desconfiar do que chega. Mesmo assinado, o conteúdo vindo de terceiros precisa de validação de tipo, tamanho e valores possíveis. O OWASP API Security Top 10, referência de riscos em APIs, inclui o consumo inseguro de APIs de terceiros entre os dez principais. Assine também só os eventos que a integração usa: receber tudo aumenta a carga e a superfície de erro.

Como escolher entre API, webhook e plataforma

Um roteiro que resolve a maioria dos casos:

1. Liste os eventos que importam (pedido pago, lead criado, nota emitida) e confira na documentação de cada sistema se existe webhook para eles. Se existe, use como gatilho. Se não, planeje consulta periódica pela API.
2. Estime o volume por dia e nos picos, como fim de mês e promoção. Volume baixo e fluxo simples apontam para plataforma; volume alto aponta para código próprio.
3. Conte as exceções. Se a regra cabe numa frase, a plataforma resolve. Se precisa de uma tabela, provavelmente não.
4. Classifique os dados. Dado pessoal e financeiro pede saber onde fica armazenado, por quanto tempo e quem acessa.
5. Defina quem mantém e quem é avisado. Integração sem dono para na primeira mudança de versão e ninguém percebe. O alerta de falha segue a mesma lógica do monitoramento de sites e sistemas.

Próximo passo

Pegue um fluxo só, o que hoje dá mais retrabalho, e passe por ele os cinco pontos acima. Com isso em mãos, a conversa com quem vai implementar fica objetiva, e dá para comparar o orçamento de uma plataforma com o de um desenvolvimento olhando para o mesmo desenho.

Se a resposta apontar para código próprio ou para um desenho misto, é o trabalho que fazemos em integração de sistemas: o fluxo é montado num ambiente isolado, testado com eventos reais da operação (inclusive os repetidos e os fora de ordem) e publicado com um caminho de volta documentado.