A decisão
Receber notificação não conclui ação de negócio. Planeje repetições e ordem diferente. A Stripe documenta esse comportamento; confira o contrato de outros fornecedores.
Um exemplo concreto
Um evento fictício de fatura paga é validado, salvo com o trabalho previsto e confirmado após aceitação persistente. A repetição é reconhecida sem crédito duplo. Falha posterior mantém estado para nova tentativa.
Alternativas a considerar
Inbox guarda entradas; outbox, trabalho criado na sua transação. Separam intenção persistente e rede. Conciliação detecta divergência mesmo sem aviso de erro.
Onde o plano falha
Não guarde IDs só em memória nem marque conclusão antes de confirmar mudanças. Trate eventos antigos por estado ou versão. Espaçe falhas temporárias e encaminhe dados inválidos para revisão.
Separe identidade de entrega e identidade de negócio
Guarde identificador do evento e referência da fatura. Vários eventos podem tratar da mesma fatura; bloquear todos após o primeiro perde mudanças válidas. Repetir um evento também não pode duplicar um crédito. Defina chave de recebimento e restrição de estado, confirmando verificações junto com a mudança real.
Valide o remetente pelo mecanismo documentado antes de aceitar. Se a assinatura usa corpo bruto, preserve os bytes recebidos em vez de reconstruir JSON. Segredos de assinatura não entram em logs ou código. Verificação, repetição e retenção pertencem ao contrato daquele fornecedor; copiar outra integração pode verificar algo errado.
Demonstre recuperação no momento difícil
Pare o worker após receber, após aceitar de forma durável e durante a alteração de negócio. Confira caixa de entrada e registro depois do reinício. Um efeito externo pode ter sido aceito antes de salvar o resultado local. Use idempotência ou conciliação quando disponíveis; um estado local não garante entrega exatamente uma vez.
Reprocessamento controlado preserva identidade e registra motivo. Dados permanentemente inválidos vão para exceção, não tentativas infinitas. Conciliação compara registros oficiais em intervalo definido. Combine quem analisa, trata urgências e confirma encerramento. Uma fila sem responsável pode guardar dados perfeitamente enquanto ninguém percebe que o trabalho parou.
Antes de contratar o projeto
Repetir causa apenas um efeito? O worker retoma após queda? Um registro pode ser investigado e repetido? Use as demonstrações no aceite da integração.