O que é um webhook
É um pedido HTTP que a plataforma de pagamentos envia ao seu servidor quando algo acontece — um pagamento aprovado, um reembolso, uma disputa. Em vez de o seu sistema perguntar de minuto a minuto se já entrou dinheiro, é avisado no momento em que entra.
Valide sempre a assinatura
Qualquer pessoa pode enviar um pedido ao seu endereço público a dizer «pagamento aprovado». Por isso cada envio leva uma assinatura HMAC-SHA256 calculada sobre o corpo da mensagem com o seu segredo. Calcule a assinatura do lado do seu servidor e compare byte a byte; se não bater certo, responda 401 e não faça mais nada.
Regras de ouro do consumidor de webhooks
Quatro regras evitam quase todos os incidentes.
- Valide a assinatura antes de ler os dados.
- Rejeite mensagens com data muito antiga — protege contra reenvios maliciosos.
- Trate cada evento de forma idempotente, usando o identificador do evento.
- Responda depressa (2xx) e faça o trabalho pesado em segundo plano.
Repetições e falhas
Se o seu servidor estiver em baixo, o envio é repetido com espera crescente. Isso significa que pode receber o mesmo evento duas vezes: guarde os identificadores já processados e ignore repetidos. No painel, o separador de webhooks mostra o histórico de envios com o código de resposta, o que torna a depuração directa.
O que nunca deve fazer
Não confie em parâmetros vindos do navegador do cliente para dar a encomenda por paga. Não use HTTP simples. Não aponte webhooks para endereços internos da sua rede. E não deixe o segredo em código do lado do cliente.