Webhooks na prática: como conectar dois sistemas sem escrever uma integração completa

Toda vez que um pagamento é aprovado na plataforma de vendas, alguém do financeiro abre o painel, copia o número do pedido, entra no sistema de gestão e muda o status para "pago". Depois, avisa a expedição por mensagem. São poucos minutos por pedido, mas a tarefa se repete dezenas de vezes ao dia, depende de alguém lembrar de fazê-la e falha quando essa pessoa sai de férias. Situações assim são o território clássico dos webhooks: um mecanismo simples que permite a um sistema avisar outro, automaticamente, quando algo acontece, sem que seja preciso construir uma integração completa entre os dois.

O que é webhook, sem jargão

Um webhook é uma notificação enviada por um sistema a outro pela internet, no momento em que um evento ocorre. Tecnicamente, é uma requisição HTTP, quase sempre do tipo POST, que o sistema de origem dispara para um endereço cadastrado previamente pelo sistema de destino.

A diferença em relação a uma integração tradicional fica clara com uma comparação. Sem webhook, o sistema de destino precisa perguntar de tempos em tempos ao de origem se há novidades, prática chamada de polling. É como ligar para a transportadora a cada hora para saber se a encomenda saiu. Com webhook, a transportadora avisa quando a encomenda sai. Menos consultas inúteis, menos atraso e menos código para manter.

Por isso o webhook é às vezes chamado de "API reversa": em vez de o seu sistema chamar a API do fornecedor, é o fornecedor que chama o seu sistema.

Três conceitos: evento, carga útil e endpoint

Todo webhook envolve três elementos.

Evento é o fato que dispara o aviso: pagamento aprovado, pedido criado, formulário enviado, chamado aberto, arquivo carregado. Os sistemas que oferecem webhooks costumam listar os eventos disponíveis e permitir escolher quais serão enviados. A documentação de plataformas como GitHub e Stripe recomenda assinar apenas os eventos de que a integração realmente precisa, para não sobrecarregar o servidor que recebe.

Carga útil (payload, em inglês) é o conteúdo da mensagem. Em geral vem no formato JSON e traz campos como:

• o tipo do evento, por exemplo pagamento.aprovado;
• um identificador único do evento;
• a data e a hora em que ele ocorreu;
• os dados do objeto envolvido, como o número do pedido, o valor e o cliente.

Endpoint é o endereço que recebe a notificação: uma URL pública, acessível pela internet e protegida por HTTPS, requisito que vários fornecedores já impõem. É ali que fica o código, ou a ferramenta, que interpreta a mensagem e decide o que fazer com ela.

Um exemplo de ponta a ponta

Voltando ao caso do pagamento, o objetivo é que, quando a plataforma de vendas aprovar um pagamento, o pedido seja marcado como pago no sistema de gestão e a expedição receba um aviso. O caminho tem sete passos.

1. Definir o evento e o resultado. O evento é "pagamento aprovado". O resultado esperado é "status do pedido atualizado e mensagem enviada ao canal da expedição". Escrever isso antes evita que a integração cresça sem controle.
2. Criar o endpoint. Pode ser uma rota em um serviço próprio, uma função executada sob demanda em um provedor de nuvem ou o gatilho de webhook de uma ferramenta de automação sem código, que gera uma URL pronta para receber as chamadas. Essa última opção costuma bastar para fluxos simples.
3. Cadastrar o endpoint na origem. No painel da plataforma de vendas, informa-se a URL, escolhe-se o evento e gera-se um segredo compartilhado, usado para assinar as mensagens.
4. Receber e validar. Ao chegar a requisição, o endpoint confere a assinatura, verifica se o tipo de evento é o esperado e descarta o que não reconhecer.
5. Responder rápido. O endpoint devolve um código de sucesso da família 2xx logo após validar a mensagem. O GitHub, por exemplo, orienta que o servidor responda em até 10 segundos; a Stripe pede que o sucesso seja devolvido antes de qualquer lógica complexa que possa causar demora.
6. Processar. Com a resposta enviada, o sistema executa o trabalho de fato: consulta o pedido, atualiza o status e manda a mensagem. Em volumes maiores, o recomendado é colocar os eventos em uma fila e processá-los de forma assíncrona.
7. Registrar. Cada evento recebido é anotado com identificador, horário, resultado do processamento e eventual erro.

Como testar antes de ligar de verdade

Testar webhooks tem uma dificuldade própria: o evento acontece em outro sistema. Algumas práticas ajudam:

• usar o ambiente de testes do fornecedor, quando existir, para gerar eventos fictícios sem mexer em dados reais;
• disparar eventos de teste pelo painel ou pela linha de comando que muitos fornecedores oferecem;
• usar o recurso de reenvio manual de entregas, disponível em várias plataformas, para repetir um evento depois de corrigir o endpoint;
• simular os casos ruins, e não só o caminho feliz: assinatura inválida, evento repetido, endpoint fora do ar, campo ausente na carga útil.

Em testes locais, o computador do desenvolvedor não tem endereço público. Ferramentas de túnel e as ferramentas de linha de comando de alguns fornecedores resolvem isso, encaminhando os eventos para a máquina local durante o desenvolvimento.

Falhas vão acontecer: registre e trate

Um webhook atravessa a internet e depende de dois sistemas no ar ao mesmo tempo. Falhas são parte do desenho, não exceção. Três comportamentos precisam ser previstos.

Reenvio. Cada fornecedor trata falhas de um jeito. A Stripe, por exemplo, tenta reenviar eventos por até três dias em modo de produção, com intervalos crescentes. Já a documentação do GitHub orienta que, se o servidor ficar fora do ar, as entregas perdidas sejam reenviadas manualmente quando ele voltar. Saber qual é a regra do sistema de origem define quanto trabalho de recuperação fica do lado de quem recebe.

Duplicidade. O mesmo evento pode chegar mais de uma vez. A defesa é tornar o processamento idempotente: guardar os identificadores dos eventos já tratados e ignorar os repetidos. Sem isso, um reenvio pode, por exemplo, gerar duas notas fiscais para o mesmo pedido.

Ordem. Eventos nem sempre chegam na ordem em que aconteceram. A Stripe afirma explicitamente que não garante essa ordem. Se a lógica depende da sequência, é mais seguro consultar a API do fornecedor para obter o estado atual do objeto do que confiar apenas na mensagem recebida.

O registro de cada evento é o que torna esses problemas visíveis. Um painel simples, ou até uma planilha alimentada pelo próprio fluxo, com a contagem de sucessos e erros por dia, permite perceber quando a integração parou de funcionar antes que o cliente reclame. Um alerta para falhas consecutivas completa o quadro.

Como validar a origem das chamadas

O endpoint é uma URL pública. Qualquer pessoa que a descubra pode enviar uma requisição falsa, e um webhook de pagamento forjado pode liberar a entrega de um produto que ninguém pagou. Por isso a validação da origem é obrigatória, não opcional.

• Assinatura com segredo compartilhado. O método mais comum é o HMAC, definido na RFC 2104, da IETF. O sistema de origem calcula uma assinatura combinando o segredo e o conteúdo da mensagem e a envia em um cabeçalho. O GitHub usa o cabeçalho X-Hub-Signature-256, com HMAC-SHA256; a Stripe usa o Stripe-Signature. O endpoint refaz o cálculo e compara os resultados.
• Comparação em tempo constante. A documentação dos fornecedores recomenda comparar as assinaturas com funções que levam sempre o mesmo tempo, para evitar ataques que exploram diferenças de tempo de resposta.
• Carimbo de tempo. Incluir o horário na assinatura permite rejeitar mensagens antigas reenviadas por um atacante, o chamado ataque de repetição. As bibliotecas da Stripe adotam, por padrão, uma tolerância de cinco minutos.
• HTTPS sempre, para que o conteúdo não trafegue em texto aberto.
• Lista de endereços IP, quando o fornecedor publica os endereços de onde envia os eventos.
• Confirmação pela API em ações críticas: antes de liberar um pedido, consultar o pagamento diretamente no fornecedor.
• Rotação do segredo periodicamente ou sempre que houver suspeita de vazamento, sem nunca gravá-lo no código ou na própria URL.

Iniciativas como a Standard Webhooks, mantida por engenheiros de várias empresas do setor, propõem um padrão comum de cabeçalhos e assinatura justamente para que cada integração não precise reaprender essas regras.

Quando o webhook não é a melhor escolha

Webhooks resolvem bem avisos pontuais entre dois sistemas. Em alguns cenários, outras soluções servem melhor: quando o volume de eventos é muito alto e exige filas de mensagens dedicadas, quando a ordem estrita das operações é essencial, quando o sistema de origem simplesmente não oferece webhooks ou quando uma consulta periódica, uma vez por dia, já atende ao negócio. Escolher a ferramenta pelo problema, e não o contrário, continua sendo a regra.