Webhook no Pix: por que a confirmação do pagamento é tão importante para sua operação

01O que é um evento de pagamento

Um webhook é uma notificação enviada pelo provedor ao seu sistema quando algo relevante acontece — normalmente, a liquidação de uma cobrança. Em vez de perguntar repetidamente se o pagamento entrou, sua aplicação é avisada.

02Idempotência: a regra que evita o dobro de tudo

Eventos podem chegar mais de uma vez. Isso não é defeito — é consequência natural de redes não confiáveis e políticas de retentativa. Seu endpoint precisa tratar o mesmo evento múltiplas vezes com o mesmo resultado final.

• Registre o identificador do evento antes de executar a ação de negócio.
• Use transação de banco de dados para evitar processamento concorrente.
• Torne a ação de negócio verificável: se já foi executada, não repita.
• Responda rápido e processe o trabalho pesado de forma assíncrona.

03Retentativas e falhas

Se o seu endpoint estiver indisponível, o provedor tende a reenviar o evento segundo uma política própria. Conhecer essa política — quantas tentativas, em que intervalo, por quanto tempo — é parte do desenho da sua operação, não um detalhe do provedor.

04Segurança do endpoint

Um endpoint de webhook é público por definição. Valide a autenticidade da requisição conforme o mecanismo oferecido pelo provedor, rejeite payloads não íntegros e nunca confie no corpo da requisição como fonte única de verdade para valores financeiros — confirme o estado consultando a transação.

05Monitoramento e impacto operacional

Meça três coisas: tempo entre liquidação e recebimento do evento, taxa de erro do seu endpoint e volume de eventos reprocessados. Desvios nessas métricas antecipam problemas que, do contrário, só aparecem no atendimento.