Eingehende Zahlungs-Webhooks bestätigen den Eingang getrennt von der Buchungsänderung, deduplizieren anhand der Ereignis-ID des Anbieters, gleichen unbekannte Ergebnisse über Anbieterabfragen ab und behandeln das interne Hauptbuch als maßgeblich bei Konflikten in Reihenfolge oder Payload.
Paketstatus: KI-unterstütztes Referenzpaket. Statische Paketvalidierung wurde bestanden; Implementierungsszenarien sind noch nicht ausgeführt und eine menschliche Fachprüfung ist vor stabiler Einführung erforderlich.
Entscheidung
Zahlungsanbieter-Webhooks treffen an einem authentifizierten Eingangs-Endpunkt ein, der die Signatur vor der Speicherung verifiziert. Ungültige Signaturen führen zu einem 401 ohne Speicherung eines Belegs. Gültige Payloads werden als Belegdatensätze gespeichert; HTTP 200 wird nach dauerhafter Speicherung, vor der Buchungsänderung, zurückgegeben. Ein schneller Deduplikations-Cache kann nach dedupe_store_ttl_days ablaufen, aber ein dauerhaftes, unveränderliches Ereignisregister bewahrt die Ereignis-ID des Anbieters mindestens für die Dauer der Hauptbuch- und Prüfungsaufbewahrung. Manual_review wird durch operator_resolution auf angewendet oder abgelehnt gesetzt. Unbekannte Ergebnisse bleiben im Abgleich, bis die Anbieterabfrage erfolgreich ist oder ein Timeout sie in manual_review überführt.
Umfang
- Empfangsbestätigung von Webhooks, Signaturverifikation, Deduplikationsspeicher, Abgleich-Worker, Anbieterabfrage-Client und Idempotenz bei Buchungsänderungen.
- Pfade zur manuellen Überprüfung und Verhalten nach Ablauf der Deduplikations-TTL.
Außerhalb dieses Blocks
- Ausgehende Webhook-Zustellung an Kunden.
- Aktualisierungen der Berechtigungsprojektion (siehe Berechtigungsblock).
- PCI-Kartendatenerfassung UI und Speicherung von Zugangsdaten.
Vertrag
- HTTP 200 zur Bestätigung des Empfangs wird nur gesendet, nachdem die Signaturprüfung bestanden wurde und die Roh-Payload mit Anbieterereignis-ID dauerhaft gespeichert ist.
- Ungültige Signatur führt zu 401; invalid_signature_stores_receipt ist false; es wird keine Belegzeile erstellt und keine Buchungsänderung geplant.
- Doppelte Anbieterereignis-IDs innerhalb von dedupe_store_ttl_days bestätigen den Erfolg ohne erneute Buchungsänderung.
- Nach Ablauf des schnellen Deduplikations-Caches wird die Anbieterereignis-ID im dauerhaften Ereignisregister geprüft; ein zuvor angewendetes Ereignis bestätigt erfolgreich ohne weitere Buchungsänderung.
- Ein wirklich neues Ereignis kann erst dann in den Abgleich eintreten, wenn seine Anbieterereignis-ID atomar in das dauerhafte Register eingefügt wurde oder eine äquivalente Einzigartigkeitsbedingung gewinnt.
- Buchungsänderungen erfolgen niemals im HTTP-Handler-Thread; sie laufen in einem Worker, der den Abgleichstatus unabhängig von der Empfangsbestätigung ändert.
- manual_review wechselt nur mit operator_resolution-Audit-Datensätzen, die für den Finanzexport geeignet sind, zu angewendet oder abgelehnt.
- Anbieterabfrage und Konflikte in der Webhook-Payload bezüglich des Betrags blockieren automatische Gutschriften und führen zu manual_review.
- Spät eintreffende Ereignisse mit älteren Wirksamkeitszeitstempeln kehren keine bereits abgeschlossenen Buchungszeilen ohne expliziten Umkehrungstyp um.
Implementierungshinweise
- Speichern Sie die rohen Webhook-Bytes vor dem JSON-Parsing, damit die Signaturprüfung wiederholt werden kann.
- Verwenden Sie reconciliation-states.yaml-Übergänge in Operator-Dashboards mit separaten Metriken für Empfangsbestätigung versus Buchungserfolg.
- Planen Sie exponentiell verzögerte Abfragen bei Anbieter-API-Fehlern; gewähren Sie keinen vorläufigen Zugriff, es sei denn, allow_provisional_access ist im Profil explizit auf true gesetzt.
- Trennen Sie Empfangsbestätigungsmetriken von Buchungsänderungsmetriken, um feststeckende Worker nach Empfang zu erkennen.
Fehlerbehandlung und Schutzmaßnahmen
- Worker-Absturz nach Empfangsbestätigung setzt mit gespeichertem Beleg fort, ohne doppelte Bestätigung an den Anbieter.
- Abfrage-Timeout über Profilgrenze führt zu manual_review statt Standard auf bezahlt.
- Idempotenzschlüssel bei Buchungsschreibvorgängen verhindern doppelte Belastungen bei Worker-Wiederholungen.
Verifikation und Betrieb
- Tests decken ungültige Signaturablehnung, Cache-Ablauf mit dauerhafter Deduplikation, manual_review-Auflösung zu angewendet und abgelehnt sowie nicht sequenzielle Rückerstattungen ab.
- Metriken verfolgen Verzögerung von Empfangsbestätigung bis Buchungsänderung, Tiefe der Abgleich-Warteschlange, Rate manueller Überprüfungen und Anzahl abgelehnter Endzustände.
- Abgleich-Simulationen testen Anbieter-Ausfälle während hoher Webhook-Volumen.
Annahmen zur Einführung
- Namen und Zahlenwerte in example.yaml und reconciliation-states.yaml sind ein Einführungsprofil, keine universellen Standardwerte.
- Das einführende Team wählt Zahlungsanbieter aus und definiert Regeln für Hauptbuch-Konflikte mit Finanzbeteiligten.