Quando uma empresa recebe pagamentos por meio de um gateway, é importante saber quando uma transação foi aprovada, recusada, cancelada ou estornada.
O webhook é uma das principais formas de receber essas atualizações automaticamente. Ele permite que o provedor de pagamento envie uma notificação ao sistema quando ocorre uma mudança na transação.
O que é um webhook?
Webhook é uma comunicação automática entre dois sistemas.
Em vez de o sistema da empresa consultar o provedor repetidamente para saber se houve alguma alteração, o próprio provedor envia uma requisição quando um evento acontece.
No caso de pagamentos, o evento pode informar que uma cobrança foi:
- Paga;
- Aprovada;
- Recusada;
- Cancelada;
- Expirada;
- Estornada;
- Colocada em análise.
O sistema recebe a notificação, valida os dados e atualiza a cobrança correspondente.
Como funciona a confirmação por webhook?
O fluxo normalmente segue estas etapas:
- A empresa cria uma cobrança no sistema;
- A cobrança é enviada ao provedor de pagamento;
- O provedor gera uma transação;
- O cliente realiza o pagamento;
- O provedor altera o status da transação;
- O provedor envia um webhook;
- O sistema valida a notificação;
- A cobrança é atualizada.
Quando o pagamento é confirmado, o sistema pode marcar a cobrança como paga e interromper lembretes futuros.
O que uma notificação de webhook contém?
O conteúdo varia conforme o provedor, mas normalmente inclui informações como:
- Tipo do evento;
- Identificador da transação;
- Identificador externo da cobrança;
- Status do pagamento;
- Valor;
- Data e horário;
- Dados do cliente;
- Informações do meio de pagamento;
- Assinatura ou mecanismo de autenticação.
O sistema não deve confiar apenas na chegada da notificação. Os dados precisam ser conferidos antes de alterar a cobrança.
Como validar um webhook?
Uma validação segura pode incluir:
- Conferência da assinatura digital;
- Validação do token ou segredo configurado;
- Verificação do provedor de origem;
- Conferência do identificador da transação;
- Comparação do valor pago com o valor da cobrança;
- Verificação do status recebido;
- Consulta adicional ao provedor, quando necessário.
A assinatura ou o segredo ajudam a confirmar que a notificação realmente veio do serviço esperado.
Por que a idempotência é importante?
Um mesmo evento pode ser enviado mais de uma vez. Isso pode acontecer por falha de rede, timeout ou tentativa automática do provedor.
Por isso, o sistema precisa reconhecer eventos já processados.
Uma forma comum é armazenar:
- Identificador único do evento;
- Identificador da transação;
- Data de processamento;
- Resultado do processamento.
Se a mesma notificação chegar novamente, o sistema não deve gerar uma segunda baixa, duplicar o recebimento ou repetir uma ação indevida.
O que acontece quando o webhook não é processado?
Se o sistema estiver indisponível ou responder com erro, o provedor pode tentar enviar a notificação novamente.
A aplicação precisa:
- Registrar o recebimento;
- Processar o evento com segurança;
- Responder corretamente ao provedor;
- Armazenar erros;
- Permitir uma nova tentativa;
- Evitar duplicidade no reprocessamento.
Também é importante acompanhar eventos que falharam para que nenhum pagamento confirmado fique sem atualização.
Quais status devem gerar baixa?
Nem todo status recebido significa que o pagamento foi concluído.
A baixa normalmente deve ocorrer somente quando o provedor indicar um status definitivo de pagamento confirmado, conforme as regras daquele serviço.
Estados como estes podem exigir tratamento diferente:
- Pendente;
- Em análise;
- Recusado;
- Cancelado;
- Expirado;
- Estornado.
A empresa deve consultar a documentação do provedor para interpretar cada evento corretamente.
Webhook e PIX
Em uma cobrança PIX criada por um gateway, o webhook pode informar quando a transação foi confirmada.
Nesse caso, o sistema pode:
- Atualizar a cobrança;
- Registrar o pagamento;
- Interromper lembretes;
- Atualizar o painel;
- Liberar o próximo ciclo da recorrência.
Já no PIX com chave própria, o funcionamento depende da existência de uma integração que forneça os dados da transação. Um comprovante enviado pelo cliente não equivale, por si só, a um webhook de confirmação bancária.
Webhook não é a mesma coisa que comprovante
O webhook é um evento técnico enviado pelo provedor que processou ou acompanha a transação.
O comprovante é um documento ou imagem enviado pelo cliente para demonstrar que realizou um pagamento.
A leitura automática de um comprovante pode ajudar a identificar valor, data e outros dados, mas pode apresentar falhas ou divergências. Por isso, pagamentos baseados apenas em comprovantes podem precisar de revisão manual.
Como proteger um endpoint de webhook?
O endpoint que recebe webhooks deve ser protegido.
Alguns cuidados importantes são:
- Usar HTTPS;
- Validar assinaturas;
- Não expor segredos no código público;
- Registrar tentativas e erros;
- Limitar requisições suspeitas;
- Não confiar em dados enviados sem validação;
- Evitar processar o mesmo evento várias vezes;
- Responder rapidamente e concluir o processamento com segurança.
Também é recomendável separar eventos de produção e testes.
O que fazer quando o pagamento não corresponde?
Pode acontecer de o valor recebido ser diferente do esperado ou de o identificador não existir no sistema.
Nesses casos, a cobrança não deve ser marcada automaticamente como paga.
A equipe pode:
- Consultar o painel do provedor;
- Verificar o identificador da transação;
- Conferir o valor;
- Analisar o cliente relacionado;
- Solicitar revisão;
- Associar o pagamento manualmente, quando for seguro.
Manter o evento em análise é mais seguro do que confirmar uma cobrança incorreta.
Como o Contro utiliza confirmações de pagamento?
O Contro pode acompanhar pagamentos de provedores integrados e atualizar as cobranças conforme as confirmações recebidas.
Depois que o pagamento é confirmado, os lembretes seguintes podem ser interrompidos e o status da cobrança pode ser atualizado no painel.
No PIX manual, o comprovante enviado pelo cliente pode ser analisado como auxílio operacional. Quando houver divergência, a cobrança deve passar por revisão antes de ser confirmada.
Conclusão
O webhook permite que o provedor avise automaticamente quando uma transação muda de status.
Para que a confirmação seja segura, o sistema precisa validar a origem, conferir os dados, evitar duplicidades e interpretar corretamente cada status.
Quando bem implementado, o webhook reduz consultas manuais, melhora a atualização das cobranças e ajuda a evitar que clientes recebam lembretes depois de pagar.
A automação deve sempre manter uma alternativa de revisão para eventos incompletos, divergentes ou não reconhecidos.
