Idempotência de webhooks: impedir efeitos de pagamento duplicados

A idempotência garante o efeito pretendido de uma operação lógica mesmo quando a entrega ou execução se repete.

Registos escuros ligados por percursos de transação índigo e um marcador de reconciliação.

A idempotência garante o efeito pretendido de uma operação lógica mesmo quando a entrega ou execução se repete. Não promete uma mensagem recebida apenas uma vez. Separe receção, armazenamento duradouro, transição de estado e tarefas seguintes como fronteiras de falha distintas.

Escolher a identidade certa

A referência do evento identifica entregas repetidas desse evento. A do pagamento relaciona eventos diferentes com um objeto comercial. A chave de idempotência de uma solicitação externa protege outra fronteira, segundo as regras do prestador. Cliente e montante não substituem estas identidades: compras legítimas podem coincidir. Defina também as transições de estado permitidas.

Guardar antes de confirmar

Valide a assinatura de acordo com a documentação do prestador e conserve o evento ou coloque-o numa fila duradoura antes de confirmar a aceitação. Ligue mudança comercial e prova de tratamento de forma atómica ou equivalente. Uma caixa de saída transacional permite retomar tarefas externas após interrupção. Proteja dados pessoais dos eventos com acesso e conservação adequados.

Ensaiar repetição e recuperação

Entregue o evento sequencialmente e em simultâneo e pare o trabalhador em cada fronteira duradoura. Verifique movimentos, acessos e chamadas externas além das respostas. Um evento tardio não deve impor um estado antigo por chegar em último lugar. Monitorize idade e estado de tarefas por terminar. A repetição controlada deve aplicar as mesmas proteções do processamento normal e deixar um rasto operacional.

Um exemplo para validar

Um trabalhador pode guardar a encomenda e parar antes de marcar o evento como terminado. Quando regressa, recebe a mesma tarefa. Verifique primeiro a proteção duradoura da encomenda e depois a entrega. Outra execução não deve conceder um segundo acesso. Se faltar entregar, deve continuar a existir uma tarefa retomável. Registe os resultados separadamente com as referências. O cenário distingue duplicar um efeito de perder trabalho posterior e permite demonstrar que uma reparação não resolve um problema à custa de criar o outro.

Stripe — Documentação de referência

Perguntas frequentes

Uma lista em memória chega?

Não. Reinícios e vários trabalhadores exigem prova persistente partilhada.

A idempotência do prestador protege o webhook?

Protege a solicitação ao prestador; os efeitos internos precisam de controlos próprios.

Devemos guardar tudo para sempre?

Não. Defina relevância, investigação e prazo de conservação.

Uma repetição pode duplicar um reembolso?

Sim, sem proteção da operação comercial; teste com dados sintéticos.

Como detetar processamento bloqueado?

Pelo estado duradouro, antiguidade, tentativas e reconciliação independente.

Da ideia a um âmbito que se consegue executar

Partilhe o percurso do utilizador, integrações e condições de lançamento. Podemos preparar uma estimativa com pressupostos e exclusões.

Consultar o âmbito do serviço →