Webhook-Reliability: Retry Queue, Signaturen und robuste Order-Reconciliation

Eine Payment-Integration ist erst dann produktionsreif, wenn sie auch bei unperfekten Zuständen korrekt bleibt. Käufer schließen Browser-Tabs. Bankbestätigungen kommen verzögert. Shop-Backends deployen während einer Zahlung. Firewalls, Timeouts und kurzlebige Datenbankprobleme treffen genau die Schnittstelle, die Orders bezahlt setzen soll. Wer Zahlungsstatus nur aus einem Redirect oder einem einzelnen Callback ableitet, baut damit eine Schwachstelle in Fulfillment, Support und Buchhaltung.

FoxPay behandelt Webhooks deshalb als operative Zustellung von Backend-Wahrheit. Der Redirect führt Käufer zurück in den Shop, Polling hält die Checkout-Ansicht aktuell, aber die Händler-Order sollte erst durch einen verifizierten, idempotent verarbeiteten Webhook final bewegt werden. Genau hier werden Retry Queue, Signaturen, Delivery-Header und Redelivery kommerziell wichtig: Sie reduzieren manuelle Nacharbeit und verhindern, dass bezahlte Orders im falschen Status hängen bleiben.

Redirect und Polling sind UX, nicht Order-Wahrheit

Ein Redirect beweist nur, dass ein Browser an einer bestimmten Stelle angekommen ist. Er beweist nicht, dass der Händler-Server den finalen Zahlungsstatus dauerhaft verarbeitet hat. Ein Käufer kann die Rückleitungsseite nie erreichen, die Verbindung kann abbrechen, oder ein Payment-Flow kann erst bestätigen, nachdem der Tab geschlossen wurde. Für die Käuferführung ist der Redirect wertvoll. Für Order-Reconciliation ist er zu schwach.

Polling hat eine ähnliche Grenze. GET /payments/{paymentId}/status kann dem Frontend zeigen, ob eine Zahlung noch wartet, verarbeitet wird oder terminal abgeschlossen ist. Das ist gut für UX, aber keine robuste Buchungslogik. Fulfillment, Rechnungsstatus, interne Finance-Objekte und Support-Historie sollten aus einer serverseitigen, signierten Zustellung entstehen. Die einfache Regel lautet: Redirect und Polling informieren, Webhooks entscheiden.

Was die FoxPay Retry Queue liefert

Der FoxPay Changelog beschreibt eine persistente Outbound-Queue für Transaktions-Webhooks. Auf dem Queue-Pfad bleibt der erste Zustellversuch inline, damit der schnelle Erfolgsfall keine zusätzliche Latenz bekommt. Scheitert diese Zustellung, wird der Job nicht verloren, sondern vom Worker erneut versucht.

Wo der Queue-Pfad für einen Merchant aktiv ist, sind bis zu 12 Zustellversuche über rund 7 Tage vorgesehen. Die heiße Phase beginnt mit kurzen Intervallen wie 30 Sekunden, 2 Minuten, 10 Minuten und 30 Minuten und verlängert sich danach über Stunden bis in einen Long-Tail über mehrere Tage. Jitter von etwa 20 Prozent verteilt Lastspitzen, damit Händler-Endpunkte nicht synchron erneut getroffen werden.

Die Rollout-Formulierung ist wichtig: Die Queue wird pro Merchant aktiviert. Ältere Shops können bis zur Umstellung noch auf dem Legacy-Pfad mit bis zu 3 Versuchen liegen. Für Händler bleibt das Architekturprinzip identisch. Webhooks sind at-least-once Delivery. Ein Handler muss mit Duplikaten, verspäteten Events und wiederholten Zustellversuchen umgehen können.

Signaturen und Header als Vertrag

Jede Custom-Webhook-Zustellung trägt eine FoxPay-Signatur. Händler sollten diese Signatur gegen den exakt rohen Request-Body prüfen, bevor irgendein Order-Zustand verändert wird. JSON nach dem Parsen neu zu serialisieren kann andere Bytes erzeugen und legitime Zustellungen fälschlich ablehnen. Die Prüfung zu überspringen ist noch riskanter, weil ein öffentlicher Endpoint dann zum Status-Mutationspunkt wird.

Der Handler sollte deshalb zuerst den rohen Payload erfassen, die Signatur prüfen und relevante Header speichern. Erst wenn diese Persistenz erfolgreich ist, sollte er 2xx zurückgeben. API-Keys und Webhook-Secrets gehören nie in Browser-Code, Artikelbeispiele oder vollständige Logs. Für Diagnose reichen Delivery-ID, Attempt, Zeitstempel, Statuscode und interne Korrelations-IDs.

Zwei Header sind für den Händlerbetrieb zentral: X-Foxpay-Delivery und X-Foxpay-Attempt. Die Delivery-ID ist der Idempotency-Anker. Speichern Sie sie mit einem Unique Constraint, idealerweise zusammen mit Merchant- oder Shop-Kontext. Kommt dieselbe Delivery-ID erneut an, wird sie als Duplikat absorbiert und darf keine zweite Fulfillment-Aktion auslösen.

X-Foxpay-Attempt ist ein 1-indexierter Versuchszähler. Er ist kein Zahlungsstatus, aber ein starkes Observability-Signal. Versuch 1 mit schneller 2xx-Antwort ist der Normalfall. Versuch 5 zeigt, dass vorher Timeout, Netzwerkfehler, 5xx oder ein Endpoint-Problem aufgetreten ist. Operations-Teams können damit erkennen, ob nur eine einzelne Order betroffen ist oder ob ein Merchant-Handler grundsätzlich instabil ist.

Idempotenz im Merchant-Backend

Deduplizieren Sie nicht nur nach transaction_id. Dieselbe Transaktion kann mehrere legitime Statusübergänge haben: pending, später processing, dann completed oder ein terminaler Fehler. Diese Events sind keine Duplikate, nur weil sie zur gleichen Transaktion gehören. Dedupliziert wird die konkrete Zustellung über X-Foxpay-Delivery; danach entscheidet eine lokale State Machine, ob der neue Status die Order bewegen darf.

Eine belastbare Webhook-Tabelle enthält mindestens Merchant-Kontext, transaction_id, order_id, FoxPay-Status, Delivery-ID, Attempt, Zeitstempel, Verifikationsstatus und eine Referenz auf den Rohpayload. Danach kann die Geschäftslogik sauber arbeiten: completed gibt Fulfillment frei, failed, cancelled oder expired führen in andere Workflows, und ein verspätetes pending darf eine abgeschlossene Bestellung nicht zurücksetzen.

Auch HTTP-Antworten gehören zur Architektur. Ein 2xx bedeutet, dass die Zustellung dauerhaft angenommen wurde. Der Handler muss dafür nicht auf ERP, Warehouse, E-Mail oder Fraud-Scoring warten. Persistieren, bestätigen, intern asynchron weiterarbeiten ist stabiler. Temporäre Serverprobleme sollten als 5xx sichtbar werden. Terminale 4xx-Klassen wie 400, 401, 403, 404 und 410 werden nicht erneut versucht und sollten nur verwendet werden, wenn der Fehler wirklich dauerhaft ist.

Redelivery, Delivery History und Ops-Recovery

Merchant-triggered Redelivery ist der Unterschied zwischen kontrollierter Recovery und manueller Datenbankkorrektur. Wenn ein Handler fehlerhaft deployt wurde, mehrere Zustellungen scheitern und der Fehler danach behoben ist, kann der Merchant die Zustellung aus dem FoxPay Panel erneut anstoßen, wo diese Funktion verfügbar ist. Die Technical Info einer Transaktion zeigt Delivery-Status, letzten Versuch, nächste Planung und Delivery-Historie. Für eigene Ops-Oberflächen steht dieselbe Historie über GET /api/transactions/{transaction_id}/webhook/history bereit.

Diese Transparenz hilft Support und Engineering gleichzeitig. Support sieht, ob eine Zahlung zugestellt wurde oder ob der Händler-Endpunkt sie abgelehnt hat. Engineering sieht Attempt-Zähler, Antwortklassen und Timing. Finance bekommt später eine nachvollziehbare Spur statt einer händisch korrigierten Order ohne Kontext.

Eine robuste Händler-Checkliste sieht so aus:

• Signatur gegen den rohen Request-Body prüfen.
• X-Foxpay-Delivery als Unique Key speichern.
• X-Foxpay-Attempt für Monitoring und Incident-Analyse erfassen.
• Erst nach dauerhafter Persistenz mit 2xx antworten.
• Downstream-Arbeit in interne Queues oder Worker verschieben.
• 4xx nur für echte terminale Fehler nutzen, temporäre Fehler als 5xx zeigen.
• Mehrere Statusübergänge pro Transaktion erlauben, exakte Delivery-Replays ignorieren.
• Späte Events nicht rückwärts in die lokale Order-State-Machine schreiben lassen.
• Order-ID, Transaction-ID, Payment-ID und Finance-Referenz früh verknüpfen.
• Redelivery und Delivery History für Recovery nutzen, nicht manuelle Status-Patches.

Fazit: Für den zweiten Versuch bauen

Webhook-Reliability ist Zahlungsinfrastruktur. Sie entscheidet, ob bezahlte Orders automatisch erfüllt werden, ob Support Fälle schnell lösen kann und ob Buchhaltung später versteht, warum ein Status geändert wurde. FoxPay liefert dafür signierte Zustellung, Delivery- und Attempt-Header, Retry Queue mit Jitter und Long-Tail, Redelivery und Delivery History. Die Händlerseite muss diese Signale ernst nehmen.

Wer Orders allein aus Redirects freigibt, baut für den Idealzustand. Wer Signaturen prüft, Zustellungen idempotent speichert, HTTP-Antworten bewusst setzt und Redelivery in den Support-Prozess einplant, baut für den Betrieb. Genau diese Disziplin macht aus einem Checkout eine belastbare Payment-Integration.