Seu webhook de pagamento caiu: o que acontece com as vendas

Existe uma falha de integração que não gera erro, não aparece em log de exceção e não derruba nada. O cliente paga, o dinheiro entra na conta, e a venda continua marcada como pendente no seu sistema. Ninguém percebe até alguém reclamar.

Como o pagamento chega até você

Quando alguém paga um PIX, quem sabe disso primeiro é a instituição de pagamento. Ela precisa te avisar, e o jeito padrão é o webhook: uma requisição HTTP que ela dispara pro endereço que você cadastrou, dizendo que a cobrança tal foi paga.

Seu sistema recebe, marca a venda como paga, libera o acesso, dispara o e-mail. Tudo depende dessa única requisição chegar.

As quatro formas de esse aviso não chegar

• O endereço está errado ou fora do ar. Deploy mudou a rota, certificado venceu, o domínio caiu.
• O webhook está cadastrado mas desativado. Parece bobo e é o caso mais comum, porque não gera erro nenhum: simplesmente nada é enviado.
• Seu servidor respondeu erro. Aí entra a regra de cada instituição, que é onde mora o perigo real.
• Você tratou o evento e falhou depois. Recebeu, respondeu 200, e explodiu ao gravar no banco. Pro remetente, entregue.

A regra que apaga venda

Instituição de pagamento não tenta pra sempre. O padrão do mercado é mais ou menos este: se o seu endpoint responde qualquer coisa fora da família 200, a entrega conta como falha e ela tenta de novo. Depois de um número de falhas seguidas, normalmente perto de quinze, a fila de sincronização é interrompida.

Interrompida quer dizer que os eventos continuam sendo gerados, entram na fila, e não saem. Seu sistema para de receber tudo, não só o que falhou. E a parte que assusta: evento parado na fila costuma ter prazo de validade, na casa de duas semanas. Passou disso, é apagado em definitivo.

Ou seja: quinze respostas ruins e um descuido de duas semanas, e as vendas daquele período não chegam nunca mais por esse caminho.

Por que responder 200 quase sempre é o certo

Parece contraintuitivo, mas o seu endpoint de webhook deve responder sucesso até pra evento que ele não entendeu ou não vai usar. Recebeu um evento de um tipo que você não trata? Responde 200 e ignora. Recebeu uma cobrança que não existe no seu banco? Responde 200.

Erro deve ficar reservado pro caso em que você quer que reenviem, tipo o banco estar temporariamente indisponível. Devolver erro por evento desconhecido é caminhar de graça pra interrupção da fila.

A rede de segurança que resolve de vez

Webhook é um mecanismo de entrega, e todo mecanismo de entrega falha. A resposta não é confiar mais nele, é não depender só dele.

O padrão que funciona é uma rotina periódica que faz o caminho inverso: em vez de esperar o aviso, ela varre as cobranças que estão pendentes há algum tempo e pergunta pra instituição, uma a uma, se aquilo já foi pago. Se foi, credita.

Isso transforma uma falha silenciosa e permanente numa demora de minutos. É a diferença entre "o seller perdeu a venda" e "a venda entrou dez minutos depois".

O que o Trilho faz

A plataforma trata as duas pontas. O endpoint que recebe os avisos responde sucesso pra qualquer evento entendido, mesmo os que não usa, justamente pra não caminhar em direção à fila interrompida. E existe uma varredura que roda a cada dez minutos, olhando as vendas pendentes recentes e reconferindo o status direto na adquirente.

Todo aviso de pagamento também passa por uma reconferência antes de creditar. Não basta a requisição dizer que foi pago: a plataforma pergunta de volta pra adquirente e só credita se ela confirmar. Isso fecha a porta pra alguém que descubra o endereço e tente forjar uma venda.

Como testar a sua

1. Gere uma cobrança de valor mínimo e pague.
2. Marque quanto tempo levou pra aparecer como paga no seu sistema.
3. Desligue o webhook de propósito e repita. Se a venda nunca entrar, você não tem rede de segurança.
4. Confira se existe alguma tela onde dá pra ver as últimas entregas e o que cada uma respondeu.