Stripe webhook: validar notificações antes de atualizar encomendas

Escolha eventos ligados a decisões concretas

Defina primeiro a decisão que cada evento pode desencadear. Confirmar uma encomenda, atualizar uma tentativa e disponibilizar um serviço são ações relacionadas, mas diferentes. Mantenha referências próprias para os objetos internos e estabeleça como o objeto da Stripe corresponde à sua encomenda. Verifique também conta, montante e moeda antes de aceitar uma transição financeira.

Numa formação online, o pagamento confirmado permite iniciar a concessão de acesso. Se essa concessão falhar, a cobrança continua a ter o seu resultado. Separar as ações permite repetir apenas a entrega. Sem essa distinção, o apoio pode confundir uma falha de disponibilização com uma falha de pagamento e pedir ao cliente uma operação que não era necessária.

Webhooks de pagamento

Valide a assinatura segundo a documentação

Siga a documentação oficial Stripe para verificar o corpo recebido e a assinatura da origem. Transformações incorretas do corpo antes da verificação podem impedir uma validação legítima. Mantenha o segredo da configuração fora do navegador e dos registos comuns. Confirme ainda que o ambiente de testes não utiliza inadvertidamente a configuração de produção.

Adyen e OrsunPay usam os seus próprios contratos de eventos. Os webhooks da OrsunPay são assinados com HMAC; isso não significa que um verificador de mensagens Stripe possa ser reutilizado sem alteração. Quando existem várias origens, separe pontos de receção ou configuração de forma explícita. A confiança vem da validação correta, não do nome de um campo no conteúdo.

Ferramentas de desenvolvimento

Confirme a receção depois de guardar o necessário

Evite executar tarefas demoradas antes de estabelecer um registo recuperável do evento. Guardar a mensagem validada e programar a sua aplicação permite controlar falhas de serviços auxiliares. A resposta de sucesso ao emissor deve refletir uma aceitação real, não ocultar um erro que deixou a mensagem apenas na memória de um processo.

Defina o significado operacional de recebido, aplicado e executado. Estes estados ajudam a localizar problemas diferentes. Um evento pode ter sido guardado enquanto a emissão de um documento ainda aguarda recuperação. Registe identificador, origem e tempos relevantes, limitando dados pessoais ao necessário. Copiar todo o conteúdo para cada sistema de registos aumenta exposição sem necessariamente melhorar a investigação.

Impeça efeitos duplicados

A repetição de eventos deve ser considerada uma situação normal de integração. Use o identificador do evento e regras atómicas no armazenamento para impedir duas execuções do mesmo efeito. Uma consulta seguida de escrita sem proteção pode falhar quando duas mensagens chegam ao mesmo tempo a processos diferentes.

Considere também mensagens atrasadas. O último evento recebido não é obrigatoriamente o mais recente na história da operação. Não deixe um estado antigo sobrescrever um resultado definitivo sem verificar a transição permitida. Quando existe contradição, consulte o objeto autorizado ou encaminhe o caso para análise. Preserve os dados necessários para explicar a decisão em vez de substituir silenciosamente a história.

Crie cenários de recuperação observáveis

Teste com assinatura incorreta, duplicação, interrupção após guardar e indisponibilidade de uma dependência. Para cada caso, escreva o estado esperado da encomenda e a ação da equipa. As documentações oficiais Stripe e Adyen ajudam a configurar as respetivas origens; as regras comerciais continuam a ser responsabilidade da aplicação.

• Uma mensagem inválida não altera qualquer encomenda.
• Uma mensagem repetida não entrega novamente o serviço.
• Uma tarefa interrompida pode retomar a partir de um registo persistente.
• Um evento atrasado não apaga um resultado válido sem verificação.

Acompanhe o que ficou por concluir

Disponibilize uma lista de eventos ou tarefas que exigem intervenção, com responsável e motivo. Os pedidos de apoio devem ser localizáveis por referência interna, sem necessidade de pedir dados sensíveis ao cliente. Uma rotina de reconciliação ajuda a encontrar confirmações que não chegaram ao fluxo comercial esperado.

As tentativas de entrega da OrsunPay são limitadas; não construa o processo sobre a hipótese de repetições infinitas. Depois de uma interrupção prolongada, pode ser necessária recuperação controlada. O objetivo final é manter um pagamento, uma história coerente e uma execução comercial verificável, mesmo quando a rede e os serviços auxiliares não funcionam à primeira tentativa.

Fontes

• Stripe — Notificações webhook
• Adyen — Notificações webhook