Webhooks de pagamento idempotentes: por que importam
O dia em que o relatório mostrou mais dinheiro do que existia no banco, e a explicação estava numa notificação repetida.
O relatório de recebimentos do dia mostrava mais dinheiro do que tinha entrado no banco. Não muito mais. O suficiente para eu passar a tarde procurando. A explicação era chata e instrutiva: o provedor tinha enviado a mesma notificação de pagamento três vezes, porque não recebeu a confirmação da primeira, e o sistema tinha acreditado nas três. Foi assim que webhooks de pagamento pararam de ser assunto de desenvolvedor e viraram assunto meu.
Webhook é o aviso que o provedor manda quando algo acontece com a cobrança. Pagou, estornou, expirou. É o que faz a baixa acontecer sem ninguém digitar. Só que a internet não é confiável, o provedor não sabe se você recebeu, e a solução dele é reenviar. Várias vezes se precisar.
Idempotente é a palavra feia que resolve isso. Significa que receber o mesmo aviso dez vezes produz o mesmo resultado que receber uma vez. Nada de novo acontece a partir da segunda.
O que webhooks de pagamento repetidos causam de verdade
- Título baixado duas vezes, com crédito que não existe no banco.
- Saldo de caixa inflado, que só aparece na conciliação do dia seguinte.
- Cliente com crédito indevido registrado na conta dele.
- Comissão calculada em cima de recebimento fantasma.
- DRE do mês com receita financeira que ninguém consegue explicar.
O quarto item é o que costuma gerar a conversa mais difícil, porque comissão paga a mais não volta com facilidade. Um problema técnico de duas linhas vira uma negociação constrangedora com a equipe comercial.
Reconfirmação: não acreditar no aviso é a atitude certa
O sistema trabalha com webhooks idempotentes e reconfirmação server-to-server dos estados críticos, pago e estornado. Traduzindo para linguagem de gente: quando chega um aviso dizendo que a cobrança foi paga, o sistema não acredita de cara. Ele volta a perguntar ao provedor, pelo canal seguro, se aquilo é verdade. Só então baixa o título.
Isso soa exagerado até você entender que um endereço de webhook é público. Qualquer um pode mandar uma mensagem pra lá dizendo que a cobrança foi paga. A reconfirmação é o que separa uma notificação legítima de uma tentativa.
Os dois erros que produzem baixa duplicada
O primeiro é técnico: aviso repetido tratado como evento novo. O segundo é humano, e é bem mais frequente. O cliente manda o comprovante no WhatsApp, alguém do time baixa o título na mão, e à noite o webhook chega e baixa de novo.
A gente resolveu o segundo caso com uma combinação simples: cobrança criada pelo hub não se baixa na mão. Se o cliente mandou comprovante, você confere o status da cobrança e espera. Levou umas semanas pra virar hábito e acabou com o problema.
| Origem da duplicidade | Como aparece | Como tratar |
|---|---|---|
| Notificação reenviada pelo provedor | Dois créditos no mesmo título | Idempotência no recebimento do evento |
| Baixa manual antes do webhook | Crédito manual e crédito automático | Regra interna: cobrança do hub não se baixa na mão |
| Retorno CNAB e webhook no mesmo título | Baixa dupla no fechamento | Uma origem por título, definida no cadastro |
| Reprocessamento de arquivo antigo | Créditos de meses anteriores | Controle do que já foi processado |
Como eu confiro se está funcionando
- Faça uma cobrança real de valor baixoPague de verdade e acompanhe o título até fechar. Teste em ambiente de teste não mostra tudo.
- Confira o total recebido contra o extratoTodo dia. É a checagem que denuncia crédito fantasma antes de virar relatório.
- Olhe títulos com mais de uma baixaSe existir algum, você tem um problema de origem, não um caso isolado.
- Teste o estornoVeja se o título reabre com histórico. Estorno silencioso é pior que estorno visível.
Onde isso encosta no resto do financeiro
Webhook confiável é o que permite que a baixa automática de títulos por origem funcione sem supervisão. E baixa confiável é o que faz a conciliação bancária fechar no mesmo dia em vez de virar caça ao tesouro no fim do mês.
A configuração dos provedores e a proteção da API interna ficam no Hub de Pagamentos. Um detalhe que vale repetir: a proteção Bearer da API interna depende do hub.apiToken, e ele precisa estar configurado em qualquer ambiente exposto.
Quem trabalha com automação em outros pontos do sistema vai reconhecer o mesmo padrão de cuidado no módulo de automação e IA: processo que roda sozinho precisa de trilha e de conferência, senão vira caixa preta.
O que eu levaria pra qualquer integração nova
- O mesmo evento chegando duas vezes não pode gerar duas baixas.
- Estado crítico é reconfirmado com o provedor antes de virar baixa.
- Existe registro de qual evento gerou qual baixa.
- Existe uma regra clara sobre quando a baixa manual é permitida.
- Alguém confere o total recebido contra o extrato todo dia útil.