Payment Webhook Doctor

O que Payment Webhook Doctor faz?

Comece pelas evidências, não por um reenvio. Reexecutar um evento em um handler com defeito pode repetir seus efeitos colaterais.

Roteie uma tarefa por vez

Problema	Leia
Falha de assinatura, segredo errado, corpo analisado, entrega antiga	references/signatures.md
Crédito duplicado, atraso na confirmação, falha após sucesso, reembolsos fora de ordem	references/reconciliation.md
4xx/5xx/timeout, recuperação, evento ausente, rollout em produção	references/incident-playbook.md
Necessita de fatos de protocolo verificados e limites de versão	references/sources.md
Necessita de um adaptador não-Stripe / M-Pesa	references/provider-boundary.md

Fluxo de trabalho

1. Estabeleça escopo: provedor, snapshot versus evento thin, modo teste/ao vivo, conta conectada, framework de endpoint e versão da API. Pergunte apenas por fatos ausentes que alterem o diagnóstico.
2. Inspecione o código do handler, migrações, valor/ moeda do pedido esperado, mapeamento de PaymentIntent criado no servidor e metadados de entrega com dados sensíveis removidos. Mantenha segredos de assinatura em variáveis de ambiente locais. Não peça aos usuários para colar segredos ou corpos de clientes no chat.
3. Verifique os bytes brutos exatos da requisição antes de analisar o JSON. Prefira o SDK oficial do Stripe para um handler em produção. O verificador incluído, sem dependências, é uma referência de diagnóstico pequena e inspecionável, não um SDK substituto.
4. Use as ferramentas locais abaixo para reproduzir a falha com fixtures sintéticas primeiro. Classifique as evidências como observadas, inferidas ou não verificadas. Uma assinatura válida autentica uma entrega; não prova que o pedido deve ser atendido.
5. Repare a menor causa e adicione um teste de regressão. Vincule pagamentos a um pedido confiável no servidor; compare valor, moeda, escopo da conta e modo. Mantenha caixa de entrada, atualização de razão e intenção de efeito colateral em uma única transação de banco de dados.
6. Verifique duplicatas, eventos distintos para o mesmo objeto, reinicialização, entrega fora de ordem, eventos com falha e reembolsos parciais/totais. Não use carimbos de data/hora de eventos como mecanismo de ordenação total.
7. Entregue descobertas, patch, evidências de teste, requisitos de integração não resolvidos e um plano explícito de reversão/recuperação. Não implante, reenvie eventos ao vivo, emita reembolsos ou transfira dinheiro sem o fluxo de trabalho autorizado do usuário.

Ferramentas locais

Execute a partir da raiz desta skill:

npm test
npm run demo

Inspecione uma fixture salva em modo de teste usando seu relógio de fixture documentado:

export DOCTOR_FIXTURE_SECRET='fixture_only_not_a_live_secret'
node scripts/doctor.mjs --body fixtures/payment.json --header fixtures/signature.txt \
  --secret-env DOCTOR_FIXTURE_SECRET --fixture-now 1794130000 \
  --normalized-out /tmp/payment-doctor-event.json
python3 scripts/ledger.py --db /tmp/payment-doctor-reference.sqlite \
  --orders fixtures/orders.json < /tmp/payment-doctor-event.json

A exportação se recusa a sobrescrever um arquivo existente. Use um caminho de saída novo ou remova deliberadamente sua própria saída sintética. A CLI Python escreve apenas no banco de dados SQLite local explicitamente nomeado. Ela espera a saída normalizada confiável do verificador; ela não verifica assinaturas por si só. Nunca a exponha como um endpoint público de webhook.

O relatório de diagnóstico normal exclui dados do cliente, payloads brutos e assinaturas. Uma exportação normalizada explícita retém identificadores e valores inteiros necessários para reconciliação local. Mantenha-a privada e fora do controle de versão.

--fixture-now é apenas para eventos de teste sintéticos antigos; ele recusa entrada em modo ao vivo. Omita-o para uma entrega atual comum. O razão de referência rejeita eventos em modo ao vivo, nunca chama o Stripe e nunca despacha linhas da caixa de saída.

Relatório obrigatório

• Resultado: o que aconteceu e se foi reproduzido.
• Evidências: arquivos/linhas, metadados de entrega sanitizados, comandos exatos, resultados observados.
• Causa raiz: causa confirmada versus hipóteses restantes.
• Reparo: patch mínimo mais implicações de migração/backfill.
• Matriz de regressão: duplicata, reinicialização, incompatibilidade de escopo, valor/moeda errado, ordenação, casos de reembolso.
• Passagem operacional: evidências de integração em modo de teste ainda necessárias; critérios de replay seguro e reversão.

Limites

O suporte é intencionalmente restrito: eventos snapshot do Stripe payment_intent.succeeded, payment_intent.payment_failed e eventos de objeto de reembolso. Eventos thin, direitos de assinatura, sessões de Checkout, disputas, semântica de pagamento multicaptura, taxas de aplicação, impostos e transferências do Connect precisam de adaptadores dedicados. Um resultado sem achados não é uma certificação de segurança ou prova de que os fundos chegaram. Consulte as referências antes de estender.