Separar receção e processamento concluído
As garantias dependem do fornecedor. A Stripe documenta duplicados possíveis e ausência de ordem garantida. Uma resposta HTTP de sucesso deve corresponder a receção duradoura ou processamento previsto, não apenas à chegada à memória.
| Situação | Comportamento esperado | Prova útil |
|---|---|---|
| Mesmo evento recebido duas vezes | Evitar repetir o efeito de negócio. | ID processado e resultado persistente. |
| Evento antigo chega depois | Não substituir cegamente um estado recente. | Estado oficial e regra de transição. |
| Processamento pesado | Receção duradoura e trabalho diferido. | Estado da fila e resultado do worker. |
| Entrega em falta | Reconciliar e recuperar segundo o fornecedor. | Diferença identificada e correção verificada. |
Construir uma receção verificável
- Verifique HTTPS, assinatura e proteção contra repetição segundo o protocolo. A Stripe verifica a assinatura sobre o corpo original; transformar JSON antes pode invalidar a verificação.
- Registe duradouramente o evento ou processamento antes da confirmação adequada. Distinga ID de entrega, ID de evento e chave de idempotência da ação.
- Teste duplicados, desordem, interrupção e reinício do worker. Consulte o estado oficial do objeto quando um evento antigo não permita decidir com segurança.
Organizar recuperação e reconciliação
Documente tentativas, prazos, eventos pendentes e reconciliação com o fornecedor. Uma confirmação rápida pode ocultar falha posterior. Acompanhe também a ação final e limite segredos e dados pessoais nos registos.
Fontes primárias
Lidar com webhooks repetidos de forma segura.
Uma notificação pode ser repetida após um tempo limite ou perda de resposta. A confiabilidade depende da verificação da origem, de um identificador de evento e do processamento que separa uma nova mensagem de uma duplicata.
- Verificar cada solicitação usando o mecanismo do provedor.
- Testar novas tentativas, duplicatas e alteração da ordem de chegada.
- Confirmar consistentemente após o processamento ou enfileiramento persistente.
Fonte primária: IETF RFC 9457 — Problem Details for HTTP APIs. Método relacionado: consultar o guia prático.