Como evitar encomendas duplicadas quando um webhook de pagamento chega duas vezes?
A criação de encomendas não deve repetir-se quando o mesmo webhook de pagamento é novamente entregue. Use o identificador de evento do fornecedor juntamente com uma chave de negócio única e…
O que contém este artigo?
Resposta curta
A criação de encomendas não deve repetir-se quando o mesmo webhook de pagamento é novamente entregue. Use o identificador de evento do fornecedor juntamente com uma chave de negócio única e guarde o estado de processamento atomicamente na base de dados. Responder com sucesso ao webhook e concluir realmente uma encomenda são etapas diferentes.
O identificador de evento e o de encomenda são proteções distintas
O identificador do fornecedor ajuda a reconhecer a entrega repetida da mesma notificação. Contudo, diferentes tipos de evento podem referir-se ao mesmo pagamento. Verificar apenas se o evento já chegou pode ser insuficiente. A associação da encomenda ao pagamento e à chave de negócio também deve ter uma regra de unicidade. A entrega repetida deve ser concebida como um cenário de falha legítimo e esperado.
Consultar primeiro a base de dados e só depois inserir um registo pode causar uma condição de corrida entre dois pedidos simultâneos. Proteja o processamento com uma restrição de unicidade e um âmbito de transação adequado. Distinga os estados «recebido», «em processamento», «concluído» e «com erro». A existência de um registo incompleto não significa que a operação terminou com sucesso.
Verificação da assinatura e fila segura
Aplique o método de verificação de assinatura do fornecedor antes das regras de negócio. Consulte a documentação oficial sobre o formato do corpo necessário. Não coloque um pedido inválido na fila como evento de pagamento normal. Depois de guardar duravelmente um evento válido, as tarefas longas podem correr numa fila controlada. Não guarde detalhes sensíveis de pagamento nos registos técnicos.
O comportamento de entrega documentado pela Stripe é referência para integrações Stripe; não presuma iguais os períodos de repetição ou formatos de assinatura de outros fornecedores. A proposta deve indicar fornecedor, tipos de evento, regras de repetição e responsável pelas tarefas falhadas. Pedidos API idempotentes são também uma camada distinta da proteção do processamento de webhooks.
A reconciliação é tão importante como evitar encomendas duplicadas
Teste o mesmo evento entregue duas vezes, simultaneamente e após interrupção do processamento. Abra uma tarefa de reconciliação se o pagamento terminar sem gerar encomenda. O ecrã operacional deve relacionar pagamento e encomenda e mostrar o que muda com o reprocessamento. O objetivo não é só evitar registos duplicados, mas detetar encomendas em falta.
Lista de verificação da implementação
- A assinatura do webhook é verificada?
- Existe uma restrição de unicidade no identificador do evento?
- A chave de encomenda ligada ao pagamento está protegida separadamente?
- O processamento interrompido pode ser retomado?
- A reconciliação pagamento–encomenda é visível?
Perguntas frequentes
Uma resposta HTTP bem-sucedida indica que a encomenda terminou?
Não. A confirmação da receção do evento e a conclusão do fluxo de negócio são registos distintos.
Todos os fornecedores têm a mesma regra de repetição?
Não. Devem prevalecer o contrato e a documentação oficiais do fornecedor escolhido.
Âmbito e limites
Esta abordagem não substitui testes de integração específicos do fornecedor. Valide pagamentos e reembolsos no ambiente de teste desse fornecedor antes da entrada em produção.
Fontes e atualidade
Verificação das fontes: 7 de outubro de 2026. As versões dos documentos associados e as condições dos fornecedores podem mudar. Consulte a versão atual da fonte relevante antes da implementação.