O que é um webhook: como sistemas avisam uns aos outros sem ficar perguntando

Existe uma pergunta que todo sistema que depende de outro precisa responder: como eu sei que algo aconteceu do outro lado? A resposta ingênua é perguntar de novo, e de novo, e de novo, até a resposta mudar. A resposta que a maioria dos serviços sérios adotou — Stripe, GitHub, Twilio, WhatsApp Business, praticamente qualquer plataforma que expõe eventos — é a oposta: em vez de você perguntar, o outro lado avisa. Esse mecanismo de aviso tem nome, webhook, e apesar de ser conceitualmente simples — é só uma requisição HTTP —, ele carrega um conjunto de armadilhas que só aparecem em produção, sob carga, com um atacante curioso testando a URL.

Este artigo explica o que é um webhook, por que ele existe, como está estruturado por dentro, e — a parte que a maioria dos tutoriais pula — os cinco problemas que todo endpoint de webhook mal escrito acaba tendo: segurança, duplicidade, lentidão, ordem e ambiente de teste. Entender essas cinco coisas separa um endpoint de webhook que funciona na demonstração de um que aguenta produção.

O problema do polling: ficar perguntando "já aconteceu?"#

A forma mais óbvia de saber se algo mudou é perguntar em intervalos. Isso se chama polling: a cada alguns segundos ou minutos, seu sistema faz uma requisição a uma API perguntando "o status do pedido 1042 mudou?", recebe a resposta, descarta se não mudou nada, e pergunta de novo daqui a pouco. É a estratégia mais simples de implementar e por isso é onde quase todo mundo começa.

O custo do polling cresce em duas direções ao mesmo tempo. Perguntar com pouca frequência significa descobrir o evento tarde — se você checa a cada cinco minutos, a notícia de que um pagamento foi aprovado pode levar quase cinco minutos para chegar, mesmo que o evento real tenha acontecido no primeiro segundo. Perguntar com muita frequência resolve a latência, mas multiplica o número de requisições: mil clientes checando o status de mil pedidos a cada segundo é um milhão de chamadas por segundo que, na esmagadora maioria das vezes, respondem "nada mudou". É desperdício de rede, de CPU do lado que responde, e de dinheiro em qualquer API cobrada por chamada.

Polling também é um jogo de adivinhação de frequência. Não existe intervalo certo, porque a frequência ideal depende de quando o evento acontece de verdade, e isso é justamente o que você não sabe de antemão. Ajustar o intervalo é sempre um compromisso entre gastar recursos à toa e demorar para reagir — um trade-off que some completamente quando o problema é resolvido de outro jeito.

A inversão: não me ligue, eu ligo para você#

O webhook resolve o problema invertendo quem inicia a conversa. Em vez de você perguntar repetidamente se algo aconteceu, você registra uma vez uma URL sua junto ao provedor, e é o provedor quem faz a chamada — exatamente no momento em que o evento ocorre, nem antes nem depois. Isso costuma ser descrito com uma frase do mundo do cinema: don't call us, we'll call you — não nos ligue, nós ligamos para você. Em engenharia de software esse padrão é conhecido como Hollywood principle, e é a mesma ideia por trás de callbacks e de arquiteturas orientadas a eventos: o controle de "quando algo acontece" migra de quem consome para quem produz.

Tecnicamente, um webhook é só uma requisição HTTP comum, só que na direção contrária ao que a maioria dos desenvolvedores está acostumado. Você está habituado a escrever código que faz chamadas HTTP para uma API — seu servidor é o cliente, a API é o servidor. No webhook, seu servidor vira o lado que recebe a chamada: ele expõe um endpoint HTTP público, e é o provedor de eventos quem age como cliente, disparando um POST para esse endereço sempre que algo relevante acontece.

A consequência direta é latência quase nula e zero desperdício. Não existe intervalo de checagem porque não existe checagem — o aviso chega no instante em que o evento ocorre, e nenhuma requisição é feita quando nada muda, porque nesse caso simplesmente nenhuma requisição é enviada. É a troca de um problema de frequência por um problema de disponibilidade: agora seu endpoint precisa estar de pé para receber a chamada quando ela vier, o que introduz uma nova classe de cuidados, que é o assunto da segunda metade deste artigo.

Anatomia de um webhook#

Toda integração via webhook tem três peças fixas. Primeiro, uma URL de destino, que você cadastra no painel do provedor ou via API — algo como https://seusite.com/webhooks/pagamento. Segundo, o evento em si, entregue como um POST HTTP cujo corpo é um payload, quase sempre JSON, descrevendo o que aconteceu. Terceiro, um ou mais headers de assinatura, que permitem provar que aquele POST realmente veio do provedor esperado e não foi forjado por qualquer pessoa que descobriu a URL.

Um payload típico carrega o tipo do evento, um identificador único e os dados relevantes. Um evento de pagamento aprovado de uma plataforma de cobrança, por exemplo, chega mais ou menos assim:

``json { "id": "evt_1PabcXYZ", "type": "payment.succeeded", "created": "2026-08-14T13:05:22Z", "data": { "payment_id": "pay_9f2c", "amount": 4990, "currency": "brl", "customer_id": "cus_88a1" } } ``

O id do evento é o detalhe mais importante do payload, e é o que menos chama atenção à primeira vista. Ele existe para permitir que quem recebe o evento distinga "este é um evento novo" de "este eu já processei antes" — uma necessidade que fica clara na seção sobre entrega duplicada, mais adiante.

O header de assinatura acompanha o POST por fora do corpo, normalmente com um nome como X-Signature ou Stripe-Signature, e carrega um hash calculado sobre o payload usando um segredo que só você e o provedor conhecem. É esse header que transforma "qualquer POST que chega nessa URL" em "um POST que eu confio que veio de quem eu esperava" — sem ele, o endpoint aceita qualquer coisa que qualquer um mandar.

Exemplos do mundo real#

Pagamento aprovado é o exemplo mais citado, e por um bom motivo. Quando um cliente paga uma cobrança, a plataforma de pagamento — Stripe, PagSeguro, Mercado Pago — dispara um webhook payment.succeeded para o backend do lojista, que então libera o pedido, envia o e-mail de confirmação e atualiza o estoque. Sem o webhook, o lojista precisaria perguntar repetidamente "esse pagamento já foi aprovado?" para cada cobrança pendente, o que é exatamente o cenário de polling descrito acima.

Push para um repositório é outro caso canônico. Quando alguém dá git push num repositório no GitHub, o GitHub pode disparar um webhook push para uma URL configurada — é assim que pipelines de CI/CD sabem que devem começar a rodar, sem que nenhum servidor de CI precise ficar consultando "tem código novo?" a cada poucos segundos.

Mensagem recebida em uma plataforma de mensageria segue o mesmo padrão. Um número de WhatsApp Business ou uma integração de chat dispara um webhook para o backend da empresa sempre que um cliente manda uma mensagem, permitindo que um chatbot ou um atendente humano responda quase em tempo real, sem manter uma conexão de polling aberta o tempo todo.

Webhook vs API tradicional: quem liga para quem#

A diferença entre webhook e uma API tradicional não está no protocolo — os dois usam HTTP — mas em quem inicia a chamada. Numa API tradicional, você é sempre o cliente: seu código decide quando perguntar, monta a requisição e espera a resposta. No webhook, os papéis se invertem para aquele fluxo específico: o provedor de eventos é quem assume o papel de cliente HTTP, e o seu sistema passa a ser o servidor que responde.

Essa inversão explica por que webhook precisa de infraestrutura pública e API tradicional não precisa. Para consumir uma API você só precisa conseguir sair — fazer requisições para fora, o que qualquer máquina atrás de NAT ou firewall corporativo consegue fazer sem configuração extra. Para receber um webhook, você precisa conseguir ser alcançado — um endpoint com endereço público, HTTPS válido, e sem bloqueio de firewall na direção de entrada. É por isso que testar webhook em localhost exige um passo extra, tratado mais adiante.

Na prática, os dois modelos convivem na mesma integração. Você usa a API tradicional para consultar dados sob demanda ou para acionar ações — criar uma cobrança, disparar uma mensagem — e usa webhook para ser avisado quando o resultado dessa ação, ou de uma ação de terceiros, muda de estado. Um não substitui o outro; eles resolvem direções opostas do mesmo problema de comunicação entre sistemas.

Os desafios que todo mundo subestima#

Até aqui, um webhook parece trivial: registre uma URL, receba um POST, leia o JSON. É exatamente essa aparência de simplicidade que faz tanta gente subestimar os problemas reais, que só aparecem quando o endpoint está exposto na internet e recebendo tráfego de verdade.

Segurança: sua URL é pública, então verifique a assinatura#

O endpoint de webhook é, por definição, uma URL pública que aceita POST de fora. Isso significa que qualquer pessoa que descubra ou adivinhe essa URL pode mandar um payload forjado — um falso "pagamento aprovado" para liberar um pedido sem pagar, por exemplo. Confiar cegamente no conteúdo de um payload só porque ele "parece" vir do provedor certo é o erro de segurança mais comum em integrações de webhook.

A defesa é verificar a assinatura HMAC que vem no header, sempre, antes de processar qualquer coisa. O provedor calcula um hash do corpo da requisição usando um segredo compartilhado, previamente combinado com você, e manda esse hash no header. Do seu lado, você recalcula o mesmo hash sobre os mesmos bytes recebidos, usando o mesmo segredo, e compara com o que veio no header. Se os dois hashes não baterem, o payload foi alterado ou não veio de quem diz ter vindo, e a requisição deve ser rejeitada sem processar nada. Um exemplo de verificação em Node.js:

```javascript const crypto = require("crypto");

function verificarAssinatura(payloadBruto, assinaturaRecebida, segredo) { const hashCalculado = crypto .createHmac("sha256", segredo) .update(payloadBruto) // bytes crus, antes do JSON.parse .digest("hex");

// comparação em tempo constante: evita vazar o hash por timing return crypto.timingSafeEqual( Buffer.from(hashCalculado), Buffer.from(assinaturaRecebida) ); } ```

Dois detalhes desse trecho não são acidente. A verificação usa o corpo bruto da requisição, antes de qualquer JSON.parse, porque a assinatura foi calculada sobre os bytes exatos que o provedor enviou — reformatar o JSON, mesmo sem mudar o conteúdo lógico, muda os bytes e quebra a comparação. E a comparação usa timingSafeEqual em vez de um simples ===, porque comparar strings caractere a caractere com early-exit vaza, por tempo de resposta, quantos caracteres iniciais bateram — uma diferença medível que um atacante paciente pode explorar para descobrir a assinatura correta aos poucos.

Entrega não confiável: o mesmo evento pode chegar mais de uma vez#

Provedores de webhook não têm garantia de que sua chamada chegou e foi processada com sucesso. Se o seu endpoint não responder com um status de sucesso (2xx) dentro de um tempo curto — timeout de rede, seu servidor caiu, seu servidor demorou demais —, o provedor assume que a entrega falhou e tenta de novo, geralmente várias vezes, com espaçamento crescente entre tentativas.

Isso cria uma possibilidade que muita gente não antecipa: o mesmo evento chegar mais de uma vez no seu endpoint. Pode acontecer de o seu processamento ter, na verdade, funcionado perfeitamente da primeira vez, mas a resposta 200 ter se perdido na rede antes de voltar ao provedor — do ponto de vista dele, a tentativa falhou, então ele reenvia um evento que você já processou. Se o seu código trata cada webhook recebido como um evento novo e o executa de novo sem checar nada, um pagamento aprovado pode liberar dois pedidos, ou enviar dois e-mails de confirmação, ou debitar duas vezes um saldo interno.

A solução é fazer do processamento uma operação idempotente, usando o id do evento para deduplicar. Antes de executar qualquer efeito colateral, o endpoint verifica se aquele id de evento já foi processado — uma tabela simples com o id como chave única resolve isso — e, se já foi, responde 200 sem repetir o trabalho. É o mesmo princípio de idempotência que se aplica a qualquer operação que pode ser tentada mais de uma vez pela mesma causa: a segunda execução com a mesma entrada não deve produzir um efeito adicional.

Responder rápido: valide, enfileire, processe depois#

O provedor espera uma resposta rápida, e "rápido" costuma significar poucos segundos. Se o seu endpoint segura a conexão aberta fazendo trabalho pesado — chamando outros serviços, gerando um PDF, mandando um e-mail de forma síncrona — antes de responder, corre o risco real de estourar o timeout do provedor. E um timeout, como visto acima, é tratado como falha de entrega, o que dispara um reenvio de um evento que, na verdade, ainda está sendo processado — abrindo caminho para duplicidade e para uma fila de retries crescendo sobre um endpoint que já está sobrecarregado.

A prática correta é separar recebimento de processamento. O handler do webhook faz o mínimo indispensável de forma síncrona — verificar a assinatura, validar o formato básico do payload, checar duplicidade pelo id do evento — e, assim que confirma que o evento é legítimo e novo, coloca o trabalho pesado numa fila (Redis, SQS, RabbitMQ, o que já existir no seu stack) e responde 200 imediatamente. Um worker separado consome essa fila no seu próprio ritmo, sem pressão de timeout externo. O endpoint de webhook vira, na prática, uma porta de entrada fina, não o lugar onde o trabalho de verdade acontece.

Ordem não garantida#

Eventos de webhook podem chegar fora da ordem em que aconteceram. Retries, múltiplos workers processando em paralelo do lado do provedor, e variação de latência de rede significam que um evento "pedido cancelado" pode, em casos raros, chegar ao seu endpoint antes de um "pedido criado" referente ao mesmo pedido, mesmo que a criação tenha ocorrido primeiro na realidade.

Depender da ordem de chegada para inferir a ordem real dos fatos é um erro sutil e comum. A correção é usar um timestamp ou um número de sequência que vem dentro do próprio payload — nunca a ordem de chegada na rede — para decidir qual é o estado mais recente. Um processamento que sempre sobrescreve o estado com "o que chegou por último" sem checar esse timestamp corre o risco de deixar um pedido marcado como criado depois de já ter sido cancelado.

Testar em ambiente de desenvolvimento local#

Um webhook exige uma URL pública, e localhost não é público — esse é o obstáculo prático número um de quem está integrando pela primeira vez. O provedor de eventos vive na internet e não tem como alcançar http://localhost:3000 rodando na sua máquina, então o fluxo natural de "recebi o evento, vejo no meu debugger" simplesmente não funciona sem um passo a mais.

A solução mais comum é um túnel que expõe a porta local com uma URL pública temporária, como ngrok ou Cloudflare Tunnel: a ferramenta cria um endereço público, do tipo https://abc123.ngrok.io, que encaminha todo tráfego recebido de volta para a porta local do seu servidor de desenvolvimento. Você cadastra esse endereço temporário no provedor enquanto desenvolve, e troca pela URL de produção real antes de publicar.

Muitos provedores também oferecem ferramentas de teste e replay direto no próprio painel, que permitem disparar manualmente um evento de exemplo para uma URL registrada, ou reenviar um evento real que já ocorreu, sem precisar esperar que a condição de negócio aconteça de novo. Vale a pena conhecer essa ferramenta específica de cada provedor antes de depender só de túnel — ela costuma ser mais rápida para testar casos específicos, como um payload malformado ou um tipo de evento raro.

Boas práticas de quem recebe#

• Endpoint dedicado por tipo de integração — não misture o webhook de pagamento com o de outro provedor no mesmo handler; cada integração tem seu próprio segredo e formato.
• Responda rápido, sempre 2xx para eventos aceitos — valide, enfileire, responda; trabalho pesado vai para um worker assíncrono.
• Verifique a assinatura em toda requisição, usando o corpo bruto e comparação em tempo constante, antes de tocar no conteúdo do payload.
• Deduplique pelo id do evento — trate cada processamento como idempotente, porque reenvio é esperado, não exceção.
• Registre logs com o id do evento em cada etapa — recebido, validado, enfileirado, processado — para reconstruir o que aconteceu quando algo falhar na investigação.

Boas práticas de quem envia#

• Assine todo payload com um segredo por integração, e documente claramente o algoritmo e o formato do header para quem consome.
• Retries com backoff crescente, não imediato e infinito — um espaçamento que aumenta a cada tentativa evita bombardear um endpoint que já está com problema.
• Timeout curto na chamada de saída — não vale a pena segurar a conexão esperando um consumidor lento; é melhor falhar rápido e deixar o mecanismo de retry cuidar disso.
• Um painel de reenvio manual para o cliente da integração, permitindo disparar de novo um evento específico sem depender de suporte técnico.

Fechando#

Um webhook é, por baixo de tudo, apenas um POST HTTP — mas é um POST que inverte quem inicia a conversa: em vez de você perguntar repetidamente se algo mudou, o provedor avisa no instante em que muda, eliminando o desperdício e a latência do polling. Essa simplicidade de superfície esconde cinco problemas que só aparecem em produção: a URL pública exige verificação de assinatura antes de confiar em qualquer payload; a entrega não é garantida, então o mesmo evento pode chegar duas vezes e o processamento precisa ser idempotente; o provedor espera resposta rápida, então trabalho pesado vai para uma fila, não para dentro do handler; a ordem de chegada não reflete a ordem real dos fatos; e testar em desenvolvimento exige expor a máquina local através de um túnel. Nenhum desses cinco pontos é opcional — cada um, ignorado, vira um incidente específico e reconhecível: pedido duplicado, dado desatualizado sobrescrevendo um mais novo, ou uma URL forjada liberando algo que nunca foi pago. Tratar o webhook com o mesmo rigor de qualquer outra fronteira pública do seu sistema é o que separa uma integração que funciona na demonstração de uma que aguenta produção.