Webhook de pagamento: o que é, como funciona e boas práticas

Um webhook de pagamento é uma notificação enviada de servidor para servidor quando um evento relevante acontece, como confirmação, expiração, cancelamento ou alteração de status de uma transação.

Ele resolve um problema importante: pagamentos nem sempre terminam no mesmo instante da chamada inicial. O cliente pode pagar depois, fechar a página ou perder conexão. O backend precisa receber a atualização mesmo sem o navegador aberto.

Webhook não é o mesmo que resposta da API

A resposta de uma API informa o resultado daquela requisição. O webhook informa um evento que aconteceu depois. Em pagamentos, os dois mecanismos normalmente trabalham juntos.

Fluxo recomendado

1. a aplicação cria ou consulta uma transação;
2. armazena o identificador interno e o externo;
3. o provedor envia um evento para a URL configurada;
4. seu servidor valida a autenticidade;
5. registra o evento recebido;
6. verifica se ele já foi processado;
7. atualiza o estado interno;
8. responde rapidamente ao remetente.

Por que eventos podem chegar repetidos

Se o remetente não recebe confirmação HTTP, ele pode reenviar o evento. Redes falham, serviços reiniciam e timeouts acontecem. Por isso, duplicidade não deve ser tratada como um caso impossível.

O processamento precisa ser idempotente: receber o mesmo evento duas vezes não pode liberar dois pedidos, gerar dois créditos ou enviar duas notas fiscais.

Validação de segurança

O método exato depende do provedor. Em geral, integrações maduras usam assinatura, segredo compartilhado ou outro mecanismo verificável. Nunca confie apenas no fato de a URL ser difícil de adivinhar.

Quando houver assinatura, valide o corpo original da requisição antes de transformá-lo, seguindo a documentação do provedor.

Responda rápido e processe com controle

Um endpoint de webhook não deve executar uma cadeia enorme de tarefas antes de responder. Uma arquitetura comum registra o evento, confirma o recebimento e processa o restante de forma controlada.

Se não houver fila disponível, ao menos mantenha o processamento curto e registre erros para reprocessamento posterior.

Logs que ajudam de verdade

• identificador do evento;
• tipo do evento;
• identificador da transação;
• horário de recebimento;
• resultado da validação;
• status HTTP devolvido;
• tentativas de processamento.

Evite gravar credenciais, tokens e dados sensíveis em texto puro.

Webhook + reconciliação

Mesmo com webhooks, uma rotina de reconciliação é recomendável. Ela compara o estado interno com a fonte de pagamento e corrige exceções raras, como um evento que ficou retido durante uma indisponibilidade.

Checklist de produção

• HTTPS obrigatório;
• validação de autenticidade;
• deduplicação;
• processamento idempotente;
• logs sem dados sensíveis;
• reprocessamento de falhas;
• monitoramento de taxa de erro;
• ambiente de teste separado.

Webhooks são uma das peças mais importantes para transformar pagamento em automação. Sem eles, a operação tende a depender de polling excessivo ou conferência manual.