API ou webhook: qual usar para integrar dois sistemas

Perguntar ou ser avisado

Na API, quem precisa do dado pergunta quando quiser. No webhook, quem tem o dado avisa quando algo acontece. A diferença está no sentido da conversa, e dela decorre quase tudo o resto. Na dúvida, use webhook quando o destino precisa reagir na hora, e API quando ele consulta sob demanda ou em volume.

Exemplos de webhook: o pagamento foi aprovado, o processo mudou de fase, o cadastro foi atualizado. Já a API atende o destino que busca um conjunto de registros no ritmo dele. Os dois costumam coexistir: o webhook avisa que algo mudou, e a API busca o detalhe.

Existe ainda uma terceira forma de integrar, o arquivo trocado em lote, que segue comum em sistema público. E o ponto mais difícil não é nenhum dos três formatos: é não perder nem duplicar evento quando algo sai do previsto.

Como a API funciona

O sistema de destino faz uma requisição ao sistema de origem e recebe a resposta na hora. Quem controla o momento é quem pergunta. Isso é ótimo para consulta pontual: abrir a ficha de um cidadão, conferir o saldo, listar o que mudou desde ontem.

O problema aparece quando o sistema precisa saber se algo mudou. Sem aviso, a saída é perguntar de tempos em tempos, prática chamada de polling. O custo é duplo: a maioria das perguntas volta com a resposta "nada novo", e entre uma pergunta e outra o dado fica desatualizado. Perguntar mais vezes reduz o atraso, mas aumenta a carga sobre quem responde.

Como o webhook funciona

No webhook, o sistema de origem chama um endereço do sistema de destino assim que o evento acontece. Não há pergunta em vazio, e a reação é rápida.

Em troca, o sistema de destino precisa estar de pé e pronto para receber a qualquer hora. E a origem decide quando chamar: se ela falhar em avisar, o destino nem sabe que perdeu algo. Por isso o desenho por webhook exige cuidados que a API de consulta dispensa, e a seção sobre reprocessamento trata desses cuidados.

Quando cada um se encaixa

Três exemplos hipotéticos, só para fixar a ideia.

• Um sistema de pagamentos precisa liberar um pedido assim que a cobrança é aprovada. Webhook: a reação tem de ser imediata.
• Um painel de gestão monta, toda manhã, o consolidado do mês anterior. API: o painel busca o volume que quer, na hora que quer.
• Um sistema de protocolo precisa mostrar o histórico completo de um processo quando o servidor abre a tela. API: é consulta sob demanda.

Quando as duas necessidades existem no mesmo fluxo, o padrão é combinar: o webhook leva só o aviso e o identificador do registro, e o destino chama a API para buscar o conteúdo atualizado.

Reprocessar sem duplicar: fila, ordem e idempotência

Uma integração que só funciona quando tudo corre bem é uma integração incompleta. Rede cai, sistema reinicia, o mesmo aviso chega duas vezes. O desenho precisa prever o que acontece quando um evento chega atrasado, fora de ordem ou repetido.

Três conceitos resolvem a maior parte disso. Uma fila é uma área de espera em que os eventos ficam guardados até serem processados. Idempotência é a propriedade de uma operação que, executada duas vezes com o mesmo dado, produz o mesmo resultado de executar uma só. E o identificador de cada evento é o que permite saber se ele já foi visto.

Quando o destino está fora do ar

Se o destino não responde, o aviso não pode simplesmente sumir. A origem guarda o evento em uma fila e tenta de novo depois, com intervalos crescentes entre as tentativas, para não bombardear um sistema que acabou de voltar. Depois de um limite de tentativas, o evento vai para uma área separada de eventos com falha, onde uma pessoa possa olhar e decidir.

Há uma consequência prática: quem recebe precisa responder rápido que recebeu, e só então processar. Se a resposta demora, a origem entende que falhou e envia de novo.

Evento fora de ordem

Com nova tentativa e mais de um caminho de entrega, a ordem de chegada deixa de ser a ordem dos fatos. O aviso "cadastro atualizado" pode chegar antes do "cadastro criado", ou o dado antigo pode chegar depois do novo e sobrescrevê-lo.

A defesa é guardar, em cada evento, o identificador do registro e uma versão dele, que pode ser um número crescente ou a data da última alteração. O destino só aplica o evento se a versão for mais nova do que a que já tem. Quando a dúvida é grande, vale o padrão híbrido: usar o aviso como gatilho e consultar a API para pegar o estado atual, em vez de confiar na ordem.

Evento repetido, tratado uma vez só

Nova tentativa implica que o mesmo evento pode chegar duas vezes. Se cada chegada gerar uma cobrança, um e-mail ou um protocolo, a duplicação vira problema de verdade.

A prática é o destino guardar o identificador dos eventos já processados e, ao receber um, conferir antes de agir. Se já está na lista, responde que recebeu e não faz nada. Assim a operação se torna idempotente na prática, mesmo que a origem repita. Isso reduz muito o risco de duplicidade, mas não o zera: a lista precisa durar tempo suficiente e a verificação precisa acontecer na mesma operação que grava o resultado.

Segurança do webhook

Um endereço que recebe chamadas de fora é um alvo. Qualquer um que o descubra pode tentar enviar um aviso falso.

• Verifique a origem. A forma comum é a origem assinar a mensagem com um segredo combinado, e o destino recalcular a assinatura e comparar. Se não bate, descarta. Cada provedor define o seu mecanismo, e o certo é seguir a documentação dele.
• Mande o mínimo de dado pessoal. O aviso pode levar só o identificador e o tipo do evento, e o destino busca o resto pela API, com autenticação. Menos dado em trânsito, menos exposição, o que também ajuda a cumprir a LGPD.
• Use conexão cifrada e guarde o segredo fora do código.

Integração por arquivo ainda tem lugar

Arquivo trocado em lote não é atraso tecnológico por definição. Em alguns casos é a melhor escolha: o dado só precisa ser consolidado uma vez por dia, a origem não suporta nada além de exportação, ou o volume é tão grande que mover tudo de uma vez é mais simples do que mil chamadas. Em muito sistema público, é a realidade do que está disponível, e um desenho consciente a respeita em vez de fingir que não existe.

Para funcionar bem, o arquivo precisa ser tratado como uma integração de verdade, e não como "um arquivo que alguém manda".

O que o desenho por arquivo precisa prever

• Nome e formato combinados. Padrão de nome, codificação, separador, colunas, tratamento de campo vazio. Mudança no formato avisada antes, e não descoberta quando a leitura quebra.
• Arquivo repetido ou incompleto. O mesmo arquivo pode ser enviado duas vezes, ou chegar cortado. Um total de registros no cabeçalho ou no rodapé, e uma verificação de integridade, ajudam a reconhecer os dois casos. O mesmo cuidado de idempotência vale aqui: reler um arquivo já lido não pode duplicar registro.
• Registro do que foi lido. Um controle simples de qual arquivo foi processado, quando e com quantos registros. Sem isso, ninguém responde com segurança "esse lote entrou?".

Como escolher para o caso concreto

Cinco perguntas costumam resolver a maior parte das decisões.

1. Quão rápido o destino precisa saber? Se a resposta é "na hora", webhook ou consulta frequente. Se é "até amanhã", arquivo ou API em lote bastam.
2. Quem controla o ritmo? Se o destino quer puxar quando puder, API. Se a origem deve empurrar quando acontece, webhook.
3. Qual o volume? Muitos registros de uma vez favorecem API paginada ou arquivo. Evento isolado favorece webhook.
4. O que a origem oferece? Nem sempre há escolha: o sistema pode expor só consulta, só exportação ou só aviso.
5. O que acontece se o evento atrasar, vier fora de ordem ou repetido? Se a resposta não está desenhada, qualquer das três vias vai dar problema.

Na prática, o desenho mais robusto costuma ser híbrido: o webhook avisa que algo mudou, a API busca o estado atual do registro, e uma conferência periódica compara os dois lados para pegar o que escapou. O arquivo entra onde não há alternativa melhor ou onde o lote é o ritmo natural do negócio.

Se você vai ligar dois sistemas e quer desenhar esse fluxo antes de escrever código, conheça o trabalho de integrações de API. Quando a integração faz parte de um sistema novo, o tema se encaixa em sistemas sob medida. E, para o caso específico do acesso de usuários, leia sobre o login com gov.br. Fale sobre a integração com a Evo Tech e descreva os dois lados.