Zahlungs-Webhooks in WooCommerce: auch die zweite Zustellung zählt

Ein Kauf, drei unabhängige Zeitabläufe

Ein Kunde bezahlt mit Karte, schließt den Tab und fragt beim Shop nach, weil seine Bestellung noch als ausstehend erscheint. Dabei laufen mindestens drei Prozesse unabhängig: die Navigation im Browser, die Zahlungsaufzeichnungen des Anbieters und die Bestellhistorie des Shops. Kurzzeitige Unterschiede bedeuten nicht automatisch einen Defekt. Die Integration muss diese Zustände wieder zusammenführen können.

Die Rückkehrseite hilft dem Kunden bei der Orientierung. Sie kann den zuletzt bekannten Status anzeigen und erklären, dass die Bestätigung noch geprüft wird. Ein erfolgreich wirkender URL-Parameter darf jedoch keine Bestellung bezahlen. Kunden können die URL neu laden, ihre Verbindung verlieren oder vor dem Webhook zurückkehren. Keine dieser Browseraktionen darf einen zweiten finanziellen Effekt auslösen.

Beim Entwurf einer Zahlungsintegration fragen wir deshalb nicht nur, ob eine Zahlung funktioniert. Wir fragen, was bei einer zweiten Zustellung passiert, wenn der Browser nie zurückkehrt oder wenn die Verarbeitung auf halbem Weg endet. Daraus entsteht ein aussagekräftigerer Prüfplan als aus einer einzigen erfolgreichen Kartenzahlung.

Absender und Zahlung getrennt prüfen

Die dokumentierte Authentifizierung des Zahlungsanbieters bildet die erste Grenze. Bei signierten Webhooks muss genau die vom Anbieter verlangte Darstellung des Requests verwendet werden. Stripe beschreibt beispielsweise die Signaturprüfung mit dem unveränderten Request-Body. Wer JSON zuerst einliest und neu serialisiert, kann dabei die zu prüfenden Bytes verändern.

Ein authentifizierter Absender beantwortet noch nicht alle fachlichen Fragen. Das Ereignis muss zum richtigen Konto und zur richtigen Umgebung gehören, die erwartete Bestellung betreffen und mit Betrag sowie Währung des Servers übereinstimmen. In unserem bevorzugten Entwurf löst ein gültiges Ereignis bei Bedarf eine Abfrage des aktuellen Zahlungsdatensatzes beim Anbieter aus.

Diese Trennung ist besonders hilfreich, wenn während der Entwicklung Test- und Live-Zugangsdaten nebeneinander bestehen. Ein korrekt signiertes Testereignis darf niemals einen echten Kauf bestätigen. Ebenso darf eine Zahlung eines anderen Kontos keine fremde Bestellung begleichen, nur weil eine Kennung vertraut aussieht. Identität, Umgebung und finanzielle Zuordnung sind eigenständige Prüfungen.

Eingang speichern, dann bestätigen

Ein kurzer Webhook-Request lässt sich leichter betreiben als ein Request, der gleichzeitig E-Mails verschickt, Zugänge bereitstellt und mehrere langsame externe Aufrufe ausführt. Wir bevorzugen einen Eingangsdatensatz für das verifizierte Ereignis und einen dauerhaft gespeicherten Auftrag für die weitere Verarbeitung. Die Bestätigung bedeutet dann, dass eine wiederaufnehmbare Verarbeitung gesichert ist.

Entscheidend ist die gemeinsame Zuverlässigkeitsgrenze von Empfang und Arbeitsauftrag. Wird nur der Eingang gespeichert, aber der Auftrag geht verloren, erinnert sich das System an ein Ereignis, das nie verarbeitet wird. Existiert der Auftrag ohne verifizierten Eingang, fehlt dem Worker möglicherweise seine Grundlage. Eine Transaktion oder ein gleichwertiger Mechanismus sollte beide Datensätze absichern.

Ein Worker-Fehler wird so zu einem prüfbaren und erneut ausführbaren Zustand. Er ist kein Grund, eine erfolgreiche Bestellung zu erfinden. Die Verwaltung muss erkennen lassen, was eingegangen ist, welche Versuche stattgefunden haben und welcher Schritt noch offen ist. Eine erfolgreiche HTTP-Antwort beweist allein nicht, dass sämtliche nachgelagerten Geschäftsvorgänge abgeschlossen sind.

Die zweite Zustellung ist ein Normalfall

Stripe beschreibt Wiederholungen und weist darauf hin, dass die Ereignisreihenfolge nicht vorausgesetzt werden sollte. Die praktische Konsequenz reicht über einen Anbieter hinaus: Eine erneute Benachrichtigung ist ein normaler Betriebsfall. Speichere die Ereignisidentität und unterscheide einen wiederholten Eingang von einer tatsächlich neuen Zahlung.

Deduplizierung und finanzielle Idempotenz lösen verwandte, aber unterschiedliche Probleme. Zwei Zustellungen desselben Ereignisses können dieselbe Ereignis-ID haben. Zwei unterschiedliche Ereignisse können dennoch dieselbe finanzielle Änderung beschreiben. Deshalb benötigt der Shop zusätzlich eine stabile Zahlungsidentität. Derselbe eingezogene Betrag darf nicht nochmals zur Auslieferung führen, nur weil eine andere Nachricht ihn beschreibt.

Eine hilfreiche Testbedingung lautet: Spiele dieselbe bestätigte Zahlung mehrmals ein und vergleiche anschließend Bestellung, Bestand und Auslieferung. Das Ergebnis muss stabil bleiben. Prüfe nicht nur den HTTP-Status. Prüfe die Datensätze, die einen Kunden oder die finanzielle Darstellung des Händlers tatsächlich beeinflussen können.

Zahlungszustand statt Ankunftsreihenfolge

Eine Zahlung kann nach einem fehlgeschlagenen Versuch erfolgreich sein. Trifft danach noch eine ältere Fehlermeldung ein, darf sie die bezahlte Bestellung nicht wieder zurücksetzen. Ein Handler, der einfach das zuletzt empfangene Etikett übernimmt, kann genau diesen Fehler verursachen. Die Ankunftszeit bildet die finanzielle Wahrheit nicht zuverlässig ab.

Wir bevorzugen ausdrückliche Übergänge anhand des aktuell geprüften Zahlungszustands und der bereits angewendeten Änderungen. Bei widersprüchlichen Ereignissen sind eine erneute Anbieterabfrage und ein sichtbarer Prüfzustand hilfreicher als ein beliebiges Überschreiben. Die Abweichung muss erklärbar bleiben; die benötigten Belege sollten erhalten werden.

Erstattungen und Zahlungsstreitfälle benötigen eigene Regeln. Eine teilweise Erstattung ist nicht automatisch eine vollständige Stornierung. Eine spätere Erfolgsmeldung darf eine endgültige Erstattung nicht auslöschen. Jede Anpassung gehört zu einer bestimmten Zahlung und einem bestimmten Betrag. Bleibt die Zuordnung unklar, sollte ein Betreiber entscheiden können, statt dass das System eine Bestellposition errät.

Den Wiederanlauf vorher entwerfen

Webhooks sind ein wichtiger Eingangskanal. Trotzdem sollte ein Shop eine Bestellung erneut mit dem Anbieter abgleichen können, wenn eine Zustellung fehlt oder die Verarbeitung unklar bleibt. Dieser Abgleich muss dieselben geprüften Übergangsregeln verwenden. Ein separates Reparaturskript mit einer anderen Definition von „bezahlt“ schafft eine zweite Wahrheit.

Wiederholungen brauchen Grenzen, Wartezeiten und einen sichtbaren Endzustand. Ein dauerhaft fehlschlagender Auftrag kann einen Betriebsfehler verdecken; ein einmaliger Handler, der still aufgibt, verhindert eine mögliche Wiederherstellung. Betreiber müssen vorübergehende Netzwerkprobleme, endgültig ungültige Ereignisse und fachliche Abweichungen unterscheiden können.

Nachvollziehbarkeit verlangt nicht, jede vollständige Anfrage unbegrenzt zu speichern. Behalte die Kennungen, Zeitpunkte, Fehlergründe und Belege, die einen Übergang verständlich machen. Beschränke den Zugriff und protokolliere standardmäßig weder Kartendaten noch Zugangsschlüssel oder vollständige personenbezogene Inhalte. Ein brauchbares Protokoll verfolgt eine Bestellung, ohne zur zweiten Kundendatenbank zu werden.

Einen Ablauf prüfen, nicht nur einen Endpunkt

Ein aussagekräftiger Test beginnt mit einem konkreten Kundenablauf. Schließe eine Zahlung ohne Rückkehr zum Shop ab. Stelle die Bestätigung doppelt zu. Unterbrich einen Worker nach dem Empfang, aber vor der Auslieferung. Wiederhole nach einem Timeout und prüfe danach Bestellung und Verlauf. So werden Annahmen sichtbar, die ein reiner Erfolgsfall im Browser offenlässt.

Ergänze einen fehlgeschlagenen Versuch mit erfolgreicher Wiederholung, eine teilweise Erstattung mit nachfolgender Benachrichtigung sowie eine Anbieterantwort mit falschem Betrag oder falscher Währung. Lege vor jedem Test fest, was unverändert bleiben muss. Das Ergebnis sollte fachlich erklärbar sein: eine Auslieferung, keine Bezahlung durch eine ungeprüfte Rückkehr und sichtbares Warten bei fehlenden Belegen.

Für VivaGo sind dies Entwicklungsgrundsätze und Abnahmeszenarien. Sie behaupten nicht, dass das noch unveröffentlichte Plugin bereits sämtliche Ereignisse oder WooCommerce-Kombinationen unterstützt. VivaGo befindet sich in Entwicklung. Geprüfte Kompatibilität und genaue Zahlungsabläufe werden mit der getesteten Version veröffentlicht. Die heutige Empfehlung ist, doppelte Zustellungen und unterbrochene Arbeit von Anfang an einzuplanen.

Quellen und weiterführende Dokumentation

• Stripe: receive events and verify webhook signatures
• Stripe: manage webhook deliveries and recovery
• WooCommerce: payment gateway API