Uma integração de pagamento não termina quando o sistema envia uma cobrança para uma API. Depois dessa etapa, a transação pode ser aprovada, recusada, cancelada, expirada, estornada ou contestada.
Essas mudanças precisam chegar ao sistema da empresa de forma rápida e confiável. Caso contrário, um pedido pago pode continuar aparecendo como pendente, um cliente pode receber acesso indevido ou o setor financeiro pode trabalhar com informações desatualizadas.
É nesse contexto que entram os webhooks, callbacks e eventos de pagamento.
Em uma integração financeira, consistência significa garantir que todos os sistemas envolvidos reconheçam o mesmo estado da transação.
O que são eventos em uma integração de pagamento?
Um evento representa uma mudança relevante no ciclo de vida de uma transação.
Alguns exemplos incluem:
- cobrança criada;
- pagamento confirmado;
- cartão recusado;
- Pix expirado;
- boleto compensado;
- pagamento cancelado;
- valor estornado;
- chargeback iniciado.
Esses eventos podem ser utilizados para atualizar pedidos, liberar produtos, ativar assinaturas, enviar notificações e registrar informações financeiras.
Qual é a diferença entre webhook e callback?
Embora os termos sejam frequentemente utilizados como sinônimos, eles podem representar mecanismos diferentes.
| Conceito | Como funciona | Uso mais comum |
|---|---|---|
| Callback | Uma função ou endereço chamado após determinada operação | Retornos imediatos dentro de um fluxo |
| Webhook | Uma requisição HTTP enviada quando um evento ocorre | Atualizações assíncronas de pagamento |
| Polling | O sistema consulta periodicamente o status | Contingência ou conferência |
| Evento | Registro de uma mudança de estado | Base para automações e integrações |
Callback
Um callback ocorre quando um sistema fornece uma função ou endereço para receber uma resposta após determinada operação.
Em um checkout, por exemplo, o usuário pode ser redirecionado para uma página de sucesso após concluir o pagamento.
Esse retorno, porém, não deve ser tratado como confirmação definitiva. O cliente pode fechar a página, perder a conexão ou manipular o redirecionamento.
Webhook
O webhook é uma notificação enviada diretamente entre servidores.
Quando uma transação muda de status, a infraestrutura de pagamentos envia uma requisição HTTP para um endpoint previamente configurado pela empresa.
Por que o webhook é mais confiável?
O webhook não depende do navegador ou da ação do usuário. Ele acontece entre sistemas e permite que o backend receba atualizações mesmo que o cliente já tenha fechado o checkout.
Por que integrações perdem consistência?
Falhas de consistência normalmente acontecem quando o sistema assume que todo evento será recebido uma única vez e na ordem correta.
Na prática, podem ocorrer situações como:
- o webhook chegar com atraso;
- o mesmo evento ser enviado mais de uma vez;
- eventos serem recebidos fora de ordem;
- o servidor estar indisponível;
- a resposta ultrapassar o tempo limite;
- a assinatura do evento ser inválida;
- o processamento falhar após o recebimento.
Por isso, uma integração robusta precisa ser preparada para falhas temporárias e comportamentos distribuídos.
Boas práticas para processar webhooks
1. Implemente idempotência
Idempotência significa que o mesmo evento pode ser processado várias vezes sem produzir efeitos duplicados.
Se um webhook de pagamento confirmado for reenviado, o sistema não deve liberar o mesmo pedido duas vezes, gerar duas notas fiscais ou duplicar um saldo.
Cada evento deve possuir um identificador único, armazenado antes ou durante o processamento.
2. Valide a autenticidade da requisição
O endpoint deve verificar se a notificação realmente foi enviada pelo provedor de pagamentos.
Isso pode ser feito por meio de:
- assinatura criptográfica;
- token secreto;
- validação de cabeçalhos;
- comparação de hash;
- autenticação mútua, quando disponível.
Nunca atualize uma transação apenas com base em dados recebidos sem validação.
3. Responda rapidamente
O endpoint deve retornar uma resposta HTTP de sucesso assim que validar e registrar o evento.
Processos mais demorados, como emissão de nota fiscal, envio de e-mail ou atualização de sistemas externos, podem ser enviados para uma fila.
Quanto mais demorado for o processamento síncrono, maior o risco de timeout e reenvio do webhook.
4. Use filas e retentativas
Filas desacoplam o recebimento do evento de seu processamento.
O fluxo recomendado é:
- receber o webhook;
- validar a origem;
- registrar o evento;
- responder ao provedor;
- processar a mensagem em segundo plano;
- repetir o processamento em caso de falha.
5. Confirme estados críticos pela API
Em operações sensíveis, o webhook pode funcionar como um gatilho, mas o sistema também pode consultar a API para confirmar o status atual da transação.
Isso reduz o risco de decisões baseadas em mensagens incompletas, antigas ou fora de ordem.
Como lidar com eventos fora de ordem?
Imagine que um sistema receba primeiro o evento “pagamento estornado” e, alguns segundos depois, “pagamento aprovado”.
Se a aplicação simplesmente aceitar o último evento recebido, poderá substituir um estado final por um estado anterior.
A solução é trabalhar com uma máquina de estados, definindo quais transições são válidas. Uma cobrança estornada, por exemplo, não deve retornar automaticamente para aprovada.
Também é recomendável registrar:
- data do evento;
- data de processamento;
- status anterior;
- status recebido;
- origem da atualização;
- identificador da transação.
Monitoramento e rastreabilidade
Uma integração confiável precisa permitir que a equipe técnica descubra o que aconteceu quando houver divergências.
Logs devem registrar o recebimento, a validação e o processamento de cada evento. Métricas também podem acompanhar taxa de falhas, tempo de resposta, quantidade de retentativas e webhooks pendentes.
Integrações mais seguras com a ExPay Brasil
A ExPay Brasil oferece infraestrutura para integração de pagamentos em sites, aplicativos e plataformas digitais. Com APIs e notificações de eventos, empresas podem acompanhar transações, automatizar processos e manter seus sistemas financeiros atualizados.
Webhooks, callbacks e eventos não são apenas recursos técnicos. Eles formam a base para que pagamentos, pedidos e dados financeiros permaneçam sincronizados ao longo de toda a operação.
