Was macht Payment Webhook Doctor?
Beginnen Sie mit den Beweisen, nicht mit einem erneuten Senden. Das erneute Abspielen eines Ereignisses in einen fehlerhaften Handler kann dessen Nebenwirkungen wiederholen.
Ein Problem nach dem anderen angehen
| Problem | Lesen Sie |
|---|---|
| Signatur fehlgeschlagen, falsches Geheimnis, geparster Body, alte Zustellung | references/signatures.md |
| Doppelte Gutschrift, verzögerte Erfüllung, Fehler nach Erfolg, Rückerstattungen außerhalb der Reihenfolge | references/reconciliation.md |
| 4xx/5xx/Zeitüberschreitung, Wiederherstellung, fehlendes Ereignis, Produktionsauslieferung | references/incident-playbook.md |
| Benötigt verifizierte Protokollfakten und Versionsgrenzen | references/sources.md |
| Benötigt einen Nicht-Stripe- / M-Pesa-Adapter | references/provider-boundary.md |
Arbeitsablauf
- Umfang festlegen: Anbieter, Snapshot vs. Thin-Event, Test-/Live-Modus, verbundenes Konto, Endpunkt-Framework und API-Version. Fragen Sie nur nach fehlenden Fakten, die die Diagnose ändern.
- Handler-Code, Migrationen, erwarteten Bestellbetrag/-währung, serverseitige PaymentIntent-Zuordnung und redigierte Zustellungsmetadaten untersuchen. Signiergeheimnisse in lokalen Umgebungsvariablen aufbewahren. Benutzer nicht bitten, Geheimnisse oder Kunden-Bodys in den Chat einzufügen.
- Die genauen rohen Request-Bytes vor dem Parsen von JSON überprüfen. Das offizielle Stripe SDK für einen bereitgestellten Handler bevorzugen. Der gebündelte, ablaufinvariante Verifizierer ist eine kleine, überprüfbare Diagnosereferenz, kein SDK-Ersatz.
- Mit den untenstehenden lokalen Tools den Fehler zuerst mit synthetischen Fixtures reproduzieren. Beweise als beobachtet, abgeleitet oder unverifiziert klassifizieren. Eine gültige Signatur authentifiziert eine Zustellung; sie beweist nicht, dass die Bestellung erfüllt werden sollte.
- Die kleinste Ursache reparieren und einen Regressionstest hinzufügen. Zahlungen an eine vertrauenswürdige serverseitige Bestellung binden; Betrag, Währung, Kontoumfang und Modus vergleichen. Inbox, Ledger-Update und Side-Effect-Intent in einer Datenbanktransaktion halten.
- Duplikate, unterschiedliche Ereignisse für dasselbe Objekt, Neustart, Zustellung außerhalb der Reihenfolge, fehlgeschlagene Ereignisse sowie teilweise/vollständige Rückerstattungen überprüfen. Ereigniszeitstempel nicht als totalen Ordnungsmechanismus verwenden.
- Ergebnisse, Patch, Testbeweise, ungelöste Integrationsanforderungen und einen expliziten Rollback-/Wiederherstellungsplan liefern. Kein Bereitstellen, erneutes Senden von Live-Ereignissen, Ausstellen von Rückerstattungen oder Überweisen von Geld ohne den autorisierten Arbeitsablauf des Benutzers.
Lokale Tools
Aus dem Stammverzeichnis dieses Skills ausführen:
npm test
npm run demo
Ein gespeichertes Testmodus-Fixture mit seiner dokumentierten Fixture-Uhr untersuchen:
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
Der Export weigert sich, eine vorhandene Datei zu überschreiben. Verwenden Sie einen neuen Ausgabepfad oder entfernen Sie Ihre eigene synthetische Ausgabe absichtlich. Die Python-CLI schreibt nur in die explizit benannte lokale SQLite-Datenbank. Sie erwartet die vertrauenswürdige normalisierte Ausgabe des Verifizierers; sie überprüft selbst keine Signaturen. Setzen Sie sie niemals als öffentlichen Webhook-Endpunkt ein.
Der normale Diagnosebericht schließt Kundendaten, rohe Payloads und Signaturen aus. Ein expliziter normalisierter Export behält die für den lokalen Abgleich erforderlichen Kennungen und ganzzahligen Beträge bei. Halten Sie ihn privat und außerhalb der Versionskontrolle.
--fixture-now ist nur für alte synthetische Testereignisse; es weigert sich, Live-Modus-Eingaben zu akzeptieren. Lassen Sie es bei einer normalen aktuellen Zustellung weg. Das Referenzbuch lehnt Live-Modus-Ereignisse ab, ruft nie Stripe auf und sendet niemals Outbox-Zeilen aus.
Erforderlicher Bericht
- Ergebnis: was passiert ist und ob es reproduziert wurde.
- Beweise: Dateien/Zeilen, bereinigte Zustellungsmetadaten, genaue Befehle, beobachtete Ergebnisse.
- Ursache: bestätigte Ursache gegenüber verbleibenden Hypothesen.
- Reparatur: minimaler Patch mit Migrations-/Backfill-Auswirkungen.
- Regressionsmatrix: Duplikat, Neustart, Bereichskonflikt, falscher Betrag/Währung, Reihenfolge, Rückerstattungsfälle.
- Operative Übergabe: noch benötigte Testmodus-Integrationsnachweise; sichere Wiedergabe- und Rollback-Kriterien.
Grenzen
Die Unterstützung ist bewusst eng gefasst: Stripe-Snapshot-payment_intent.succeeded, payment_intent.payment_failed und Rückerstattungsobjekt-Ereignisse. Thin-Ereignisse, Abonnementberechtigungen, Checkout-Sitzungen, Streitfälle, Zahlungssemantik mit mehrfachem Capture, Anwendungsgebühren, Steuern und Connect-Transfers benötigen dedizierte Adapter. Ein Ergebnis ohne Funde ist keine Sicherheitszertifizierung oder ein Nachweis, dass Gelder angekommen sind. Siehe die Referenzen, bevor Sie erweitern.