Webhook é o que transforma um checkout em venda automática: em vez de o seu sistema ficar perguntando se o pagamento caiu, o gateway avisa no instante em que cai.
É simples de ligar e fácil de errar. Os erros abaixo são os que aparecem em produção, e o primeiro deles entrega produto de graça.
Por que webhook, e não consulta repetida
Consultar de tempos em tempos (polling) funciona no protótipo e degrada rápido: gasta requisição à toa, atrasa a entrega pelo intervalo entre consultas e piora conforme o número de cobranças abertas cresce.
O webhook inverte: uma chamada, no momento exato. Cliente paga, seu sistema é avisado, entrega acontece.
O fluxo mínimo
- Ao criar a cobrança, você informa a URL do seu webhook e um identificador único do pedido.
- O cliente paga.
- O gateway chama sua URL informando qual cobrança foi paga.
- Seu sistema confirma, marca o pedido e libera o produto.
- Você responde rapidamente para o gateway não tentar de novo.
Os cinco cuidados que decidem se funciona
1. Nunca confie no corpo da requisição
É o mais importante. Seu endpoint está na internet aberta — qualquer pessoa pode chamá-lo dizendo que o pedido 123 foi pago. Se você libera com base nisso, criou uma porta para receber produto sem pagar.
Faça sempre uma das duas coisas, de preferência as duas: valide a assinatura que o gateway envia no cabeçalho, e consulte a API para confirmar o status daquela cobrança antes de liberar. Trate o payload como aviso, não como prova.
2. Trate chamada repetida
O mesmo webhook pode chegar duas ou mais vezes — retentativa por timeout, reenvio do gateway, instabilidade de rede. Sem proteção, o cliente recebe o produto duas vezes ou o saldo é creditado em dobro.
A defesa é simples: antes de processar, verifique se aquele pedido já está marcado como pago. Se estiver, responda sucesso e não faça mais nada. Isso se chama idempotência, e é obrigatório aqui.
3. Responda antes de fazer o trabalho pesado
O gateway espera resposta rápida. Se o seu handler envia e-mail, gera PDF e chama outras APIs antes de responder, ele pode estourar o tempo limite — e o gateway reenvia achando que falhou.
Marque o pedido como pago, responda, e deixe o resto para depois: fila, job em segundo plano, o que for.
4. Use identificador único de verdade
Cada cobrança precisa de uma referência única do seu lado. Se dois pedidos compartilham a mesma, você não consegue saber qual foi pago. Combine algo do pedido com algo variável — nunca apenas o ID do usuário.
5. Registre tudo
Guarde cada chamada recebida: corpo, cabeçalhos, hora e o que seu sistema decidiu. No dia em que um cliente disser que pagou e não recebeu, esse log é a diferença entre resolver em dois minutos e passar a tarde no escuro.
Testando antes de ir para produção
- Faça uma compra real de valor baixo. Nada substitui o fluxo completo com dinheiro de verdade.
- Simule chamada repetida. Envie o mesmo webhook duas vezes e confirme que o produto é entregue uma só.
- Simule chamada falsa. Chame seu endpoint sem assinatura válida e confirme que ele recusa.
- Teste com o servidor lento. Veja o que acontece se a resposta demorar.
Erros comuns de ambiente
A URL precisa ser pública e acessível pela internet — endereço local não recebe chamada externa. Ela deve responder em HTTPS. E se houver camada de proteção na frente, confirme que ela não está bloqueando as chamadas do gateway.
Na LunarPay
Ao criar a cobrança pela API você informa a URL de callback e o identificador do pedido. Quando o pagamento é confirmado, essa URL é chamada — é o gancho para liberar acesso, dar baixa no pedido ou avisar seu cliente.
Vale aplicar aqui os mesmos cuidados descritos acima, principalmente confirmar o status pela API antes de liberar e ignorar chamadas repetidas do mesmo pedido.
Seja o primeiro a comentar.