Que fait Payment Webhook Doctor ?
Commencez par les preuves, pas par un renvoi. Rejouer un événement dans un gestionnaire défaillant peut répéter ses effets de bord.
Traitez une tâche à la fois
| Problème | Lire |
|---|---|
| Échec de signature, mauvais secret, corps parsé, ancienne livraison | references/signatures.md |
| Crédit en double, exécution retardée, échec après succès, remboursements désordonnés | references/reconciliation.md |
| 4xx/5xx/timeout, reprise, événement manquant, déploiement en production | references/incident-playbook.md |
| Besoin de faits protocolaires vérifiés et de limites de version | references/sources.md |
| Besoin d'un adaptateur non-Stripe / M-Pesa | references/provider-boundary.md |
Workflow
- Établissez le périmètre : fournisseur, capture instantanée ou événement léger, mode test/ live, compte connecté, framework d'endpoint et version d'API. Ne demandez que les faits manquants qui changent le diagnostic.
- Inspectez le code du gestionnaire, les migrations, le montant/la devise attendus de la commande, le mappage PaymentIntent créé côté serveur et les métadonnées de livraison expurgées. Gardez les secrets de signature dans les variables d'environnement locales. Ne demandez pas aux utilisateurs de coller des secrets ou des corps clients dans le chat.
- Vérifiez les octets bruts exacts de la requête avant d'analyser le JSON. Préférez le SDK Stripe officiel pour un gestionnaire déployé. Le vérificateur autonome sans dépendances fourni est une petite référence de diagnostic inspectable, pas un SDK de remplacement.
- Utilisez les outils locaux ci-dessous pour reproduire le défaut d'abord avec des fixtures synthétiques. Classez les preuves comme observées, inférées ou non vérifiées. Une signature valide authentifie une livraison ; elle ne prouve pas que la commande doit être exécutée.
- Réparez la cause la plus petite et ajoutez un test de régression. Liez les paiements à une commande serveur de confiance ; comparez le montant, la devise, le champ d'application du compte et le mode. Gardez la boîte de réception, la mise à jour du journal et l'intention d'effet de bord dans une seule transaction de base de données.
- Vérifiez les doublons, les événements distincts pour le même objet, le redémarrage, la livraison désordonnée, les événements échoués et les remboursements partiels/totaux. N'utilisez pas les horodatages des événements comme mécanisme d'ordonnancement total.
- Livrez les résultats, le correctif, les preuves de test, les exigences d'intégration non résolues et un plan de restauration/reprise explicite. Ne déployez pas, ne renvoyez pas d'événements live, n'émettez pas de remboursements et ne transférez pas d'argent sans le workflow autorisé de l'utilisateur.
Outils locaux
Exécutez depuis la racine de ce skill :
npm test
npm run demo
Inspectez une fixture de test enregistrée en utilisant son horloge de fixture documentée :
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
L'exportation refuse d'écraser un fichier existant. Utilisez un nouveau chemin de sortie ou supprimez délibérément votre propre sortie synthétique. La CLI Python écrit uniquement la base de données SQLite locale explicitement nommée. Elle attend la sortie normalisée de confiance du vérificateur ; elle ne vérifie pas elle-même les signatures. Ne l'exposez jamais comme point de terminaison de webhook public.
Le rapport de diagnostic normal exclut les données client, les payloads bruts et les signatures. Une exportation normalisée explicite conserve les identifiants et les montants entiers nécessaires à la réconciliation locale. Gardez-la privée et hors du contrôle de version.
--fixture-now est uniquement pour les anciens événements de test synthétiques ; il refuse les entrées en mode live. Omettez-le pour une livraison courante ordinaire. Le journal de référence rejette les événements en mode live, n'appelle jamais Stripe et n'envoie jamais de lignes de boîte d'envoi.
Rapport requis
- Résultat : ce qui s'est passé et si c'est reproduit.
- Preuves : fichiers/lignes, métadonnées de livraison nettoyées, commandes exactes, résultats observés.
- Cause racine : cause confirmée versus hypothèses restantes.
- Réparation : correctif minimal ainsi que les implications de migration/backfill.
- Matrice de régression : doublon, redémarrage, non-concordance de portée, mauvais montant/monnaie, ordre, cas de remboursement.
- Transfert opérationnel : preuves d'intégration en mode test encore nécessaires ; critères de rejeu et de restauration sûrs.
Limites
Le support est intentionnellement restreint : événements Stripe instantanés payment_intent.succeeded, payment_intent.payment_failed, et objets de remboursement. Les événements légers, les droits d'abonnement, les sessions Checkout, les litiges, les sémantiques de paiement multicapture, les frais d'application, les taxes et les transferts Connect nécessitent des adaptateurs dédiés. Un résultat sans constatation n'est pas une certification de sécurité ou une preuve que les fonds sont arrivés. Voir les références avant d'étendre.