Imagine que você vende online e quer que, assim que um cliente pagar, o pedido seja liberado e um e-mail seja enviado. Você poderia consultar o sistema de pagamento a cada minuto perguntando “já pagou?”. Funciona, mas é lento e desperdiça pedidos. O webhook inverte a lógica: é o sistema de pagamento que avisa você, no instante em que o pagamento acontece.
Para entender onde isso se encaixa, é útil saber o que é API e para que serve.
Como um webhook funciona
O processo tem poucos passos:
- Você cadastra uma URL no serviço, por exemplo https://seusite.com.br/avisos/pagamento. É o endereço que receberá os avisos.
- Você escolhe os eventos que quer receber, como “pagamento aprovado” ou “assinatura cancelada”.
- Quando o evento acontece, o serviço faz uma requisição HTTP (normalmente POST) para a sua URL, com os dados do evento, quase sempre em JSON (veja JSON: o que é e como ler).
- Seu sistema recebe, confere, processa e responde com um código de sucesso (família 2xx, como 200).
- Se não houver resposta de sucesso, o serviço tenta de novo mais tarde, algumas vezes.
Ou seja, seu sistema precisa ter um endereço público, acessível pela internet, pronto para receber esses pedidos.
Webhook ou API: quando usar cada um
- API (você pergunta): serve quando você precisa de uma informação sob demanda, como consultar o status de um pedido ou buscar a lista de produtos.
- Webhook (o serviço avisa): serve para reagir a eventos, sem desperdício de consultas e quase em tempo real.
- Os dois juntos: é comum receber o aviso por webhook e, em seguida, consultar a API para obter os detalhes completos e confirmar o que aconteceu.
Usos comuns
- pagamento aprovado, recusado ou estornado;
- novo pedido em uma loja virtual;
- mensagem recebida em um chatbot (como em chatbot no WhatsApp com a API oficial);
- formulário preenchido ou novo cadastro;
- atualização de status de entrega;
- integração entre ferramentas de automação, como as de n8n, Zapier ou Make, que recebem webhooks para disparar fluxos.
Como receber um webhook com segurança
Como o endereço é público, qualquer pessoa que o descubra pode tentar enviar avisos falsos. Cuide de:
Validar a autenticidade
A maioria dos serviços assina o aviso. Eles enviam um cabeçalho com uma assinatura calculada com um segredo compartilhado entre você e eles. Seu código recalcula a assinatura e compara. Se não bater, rejeite. Siga exatamente a documentação do serviço, pois o método varia. O segredo fica em variável de ambiente (veja variáveis de ambiente e arquivo .env).
Usar HTTPS
O endereço do webhook deve ser https, para que os dados trafeguem criptografados.
Não confiar cegamente nos dados
Valide o formato do que chega. Para eventos que movimentam dinheiro, como pagamento aprovado, é boa prática confirmar o status consultando a API oficial antes de liberar o produto.
Responder rápido
O serviço espera uma resposta em poucos segundos. Se o seu processamento for demorado, responda 200 logo e coloque o trabalho em uma fila ou tarefa em segundo plano. Se demorar demais, o serviço entende que falhou e reenvia, causando duplicidade.
Tratar eventos repetidos
Mesmo funcionando bem, o mesmo evento pode chegar mais de uma vez. A defesa é a idempotência: guarde o identificador único de cada evento (o serviço costuma enviar um) e, se ele já foi processado, ignore. Assim, um reenvio não cobra duas vezes nem envia dois e-mails.
Não depender da ordem
Os avisos podem chegar fora de ordem. Um “pedido pago” pode chegar antes de um “pedido criado”. Use as datas ou versões dos eventos e, se preciso, consulte a API para o estado atual.
Como testar durante o desenvolvimento
O serviço precisa alcançar o seu endereço, e um computador de casa normalmente não é visível da internet. Opções:
- Painel de testes do serviço: muitos permitem enviar um evento de exemplo.
- Túneis temporários: ferramentas que expõem uma porta da sua máquina em uma URL pública por um tempo. Use só para testes e feche depois.
- Sites de inspeção de requisições: mostram o que o serviço enviou, útil para entender o formato antes de programar.
- Ambiente de testes (sandbox) do serviço, quando existe, para simular eventos sem dinheiro real.
Registre em log tudo o que chegar durante o desenvolvimento. Com os dados reais em mãos, fica fácil entender a estrutura e achar erros (técnicas em como ler mensagens de erro e depurar código).
Um fluxo de exemplo do começo ao fim
Para fixar a ideia, acompanhe uma venda online:
- O cliente paga no checkout.
- O serviço de pagamento envia um webhook para o endereço da loja com o evento “pagamento aprovado” e um identificador único.
- A loja verifica a assinatura e confere se esse identificador já foi processado.
- Se for novo, registra o evento, responde com sucesso e coloca numa fila a tarefa de liberar o pedido.
- O processo em segundo plano atualiza o pedido, envia o e-mail e avisa a expedição.
- Se o aviso chegar de novo, a loja reconhece o identificador e não repete nada.
Cada passo responde a um risco: falsificação, duplicidade e lentidão.
Problemas frequentes
- Nada chega: a URL está errada, o servidor está fora do ar ou algum firewall bloqueia.
- O serviço marca falha: sua resposta não foi 2xx, ou demorou demais.
- Assinatura inválida: você alterou o corpo antes de verificar, usou o segredo errado ou o ambiente de teste e o de produção estão trocados.
- Eventos duplicados: falta o controle de idempotência.
- Alterações de endereço: se o site mudar de domínio, lembre-se de atualizar a URL cadastrada no serviço.
Para começar, implemente um endereço que apenas registra o que recebe e responde 200. Depois acrescente validação de assinatura, controle de duplicidade e só então a ação de verdade. Esse caminho em camadas é o mais seguro.