Webhook de pagamento: processe repetições sem duplicar efeitos

O pedido foi pago, o servidor respondeu tarde e a notificação chegou novamente. Na loja fictícia Oficina Digital, o teste só passa se houver uma baixa e uma liberação do produto. Use esse cenário na homologação antes de colocar uma integração de pagamentos em produção.

Webhooks podem se repetir, atrasar ou chegar fora de ordem. A documentação da Stripe, consultada em 6 de outubro de 2026, descreve explicitamente esses comportamentos. O projeto deve lidar também com entrega não concluída, pois tentativas finitas não garantem que toda notificação será recebida. A conciliação continua necessária.

Separe três identificadores

Identificador de entrega, identificador do evento e identificador do pagamento podem representar coisas diferentes. Descubra na documentação do provedor qual permanece estável numa repetição. Uma chave que muda a cada tentativa não impede processar o mesmo evento novamente.

Somente deduplicar pelo pagamento pode apagar mudanças legítimas, como uma devolução posterior. Somente deduplicar pelo evento pode deixar dois eventos distintos produzirem a mesma entrega. Defina a regra da operação interna além da chave de transporte.

Confirme a origem antes de aceitar

Implemente a autenticação exigida para o produto e a versão contratados. Não existe um cabeçalho HMAC universal que funcione para todos os gateways. Na Stripe, a verificação usa o corpo original e a assinatura prevista na documentação; transformar o corpo antes da validação pode invalidá-la.

Valide também ambiente, conta destinatária e tipo de evento. Segredos ficam fora dos registros de aplicação. Uma notificação válida para outra conta ou para testes não deve liberar um pedido real. Em dúvida sobre o estado, consulte a API autenticada do prestador, em vez de confiar em parâmetros enviados pelo navegador do comprador.

Persista antes de confirmar o recebimento

Uma arquitetura possível grava o evento validado numa caixa de entrada durável e responde rapidamente ao provedor. O trabalho demorado segue por um consumidor separado. Se a gravação falhar, o endpoint não deve declarar recebimento bem-sucedido.

O fluxo abaixo é pseudocódigo editorial, não implementação pronta de um gateway:

receber e validar conforme o contrato do provedor
persistir evento com chave única de provedor, conta e evento
confirmar recebimento após a gravação durável
consumidor: iniciar transação no banco
conferir estado e regra da operação comercial
aplicar mudança permitida e registrar efeito pendente
marcar evento processado e confirmar transação
entregar efeito pendente com proteção contra repetição

Para efeitos externos, como envio de produto ou mensagem, gravar uma intenção de execução na mesma transação ajuda a evitar a lacuna entre atualizar o banco e publicar a ação. Esse é o propósito do padrão transactional outbox, descrito pela AWS. O consumidor dessa fila ainda precisa de idempotência; a fila não torna uma chamada externa atomicamente ligada ao banco.

Trate ordem e criação de cobrança separadamente

Um evento antigo não deve rebaixar automaticamente um pedido já devolvido para “pago”. Modele transições permitidas e use consulta ao provedor quando o histórico recebido for insuficiente. Preserve registros necessários para explicar a decisão.

Na direção oposta, ao criar pedidos, use a chave de idempotência prevista pela API. A documentação do Pagar.me informa duração de 24 horas na produção e cinco minutos no ambiente de testes. Grave a chave junto à operação antes da primeira tentativa; um reinício do processo não deve inventar outra chave para repetir a mesma criação. Depois da janela aplicável, consulte o estado antes de tentar novamente.

Homologue falhas com resultado esperado

Defina alertas pela fila pendente, idade dos eventos e diferença entre extrato e pedidos. Limites devem refletir o serviço contratado e a operação; números universais de tentativas ou latência podem esconder incidentes.

Se o pagamento dispara relacionamento, o roteiro de validação de plataforma do Portal Leadlovers ajuda a exigir demonstração da integração. Envie apenas os dados necessários à sequência e estabeleça política de retenção conforme finalidade e obrigações aplicáveis, sem adotar um prazo universal para todo payload.

A Oficina Digital aprova a integração quando consegue repetir o teste da abertura e recuperar uma notificação perdida. Guarde as evidências desses cenários com a versão da documentação utilizada.

Fontes e critérios da revisão

Consulta editorial em 06/10/2026. Exemplos numéricos identificados como hipotéticos não representam tarifas, pesquisas ou resultados de clientes. Confirme condições contratuais antes de decidir.

• Stripe: assinatura, repetição, ordem e entrega de eventos
• Pagar.me: idempotência e diferenças entre produção e testes
• AWS: padrão transactional outbox
• Portal Leadlovers: validação de integração e critérios de aceite