Webhook-Zuverlässigkeit in Zahlungssystemen (Webhook Zuverlaessigkeit In Zahlungssystemen)

Ein Webhook ist keine garantierte Nachricht

Ein Webhook, den der PSP Ihnen sendet, trägt keine Garantie, dass „dieses Ereignis genau einmal und in der richtigen Reihenfolge ankommt“. Im Gegenteil, er kann auf vier Arten kaputtgehen: dasselbe Ereignis kann mehrfach ankommen, ein Ereignis kann nie ankommen, Ereignisse können in anderer Reihenfolge ankommen als gesendet, und ein Ereignis kann Minuten später verspätet eintreffen.

PSP → Webhook
  ⚠ Duplicate: dasselbe Ereignis zweimal
  ⚠ Missing: das Ereignis kommt nie an
  ⚠ Out-of-order: die Capture-Benachrichtigung kommt vor der Authorize-Benachrichtigung an
  ⚠ Delayed: ein Ereignis kommt Minuten später an

Dieser Teil erklärt, wie Sie Ihren Webhook-Handler gegen alle vier Szenarien widerstandsfähig machen.

Begriffe, dort definiert, wo sie zuerst auftauchen

📦 Webhook
Ein HTTP-Aufruf, den ein externes System (der PSP) an Ihren Endpunkt macht, um ein auf seiner Seite eingetretenes Ereignis zu melden.

📦 Signature Verification
Eine kryptografische Prüfung, die bestätigt, dass ein eingehender Webhook wirklich vom PSP stammt und der Inhalt nicht verändert wurde.

📦 At-least-once Delivery
Ein Zustellmodell, das garantiert, dass ein Ereignis mindestens einmal ankommt, manchmal öfter — aber keine Garantie zu Reihenfolge oder Anzahl der Wiederholungen gibt.

📦 ACK (Acknowledgement)
Die schnelle HTTP-Antwort (meist 200), mit der ein Webhook-Empfänger dem PSP bestätigt, das Ereignis erhalten zu haben.

📦 Durable Write
Das Schreiben des Ereignisses in einen dauerhaften Speicher, unabhängig davon, was danach passiert — nicht nur ein Halten im Arbeitsspeicher.

Alle diese Begriffe dienen einer Regel: Ihr Webhook-Handler muss das eingehende Ereignis zuerst sicher erfassen, egal was passiert, und erst danach die schwere Arbeit erledigen.

Duplicate: dasselbe Ereignis kommt zweimal

Erhält der PSP von Ihnen keine rechtzeitige 200-Antwort (Netzwerkproblem, Serverträgheit), sendet er dasselbe Ereignis erneut. Das ist kein Bug, sondern die natürliche Folge der At-least-once-Garantie des PSP. Das Event-ID-plus-Inbox-Muster aus Teil fünf ist hier Ihre erste Verteidigungslinie.

Webhook #1: evt_001 → verarbeitet
Webhook #2: evt_001 (erneute Zustellung) → bereits in der Inbox, Verarbeitung übersprungen, 200 zurückgegeben

Missing: das Ereignis kommt nie an

Manchmal taucht ein Webhook nie auf: ein Netzwerkausfall, ein Fehler auf PSP-Seite oder Ihr Endpunkt ist vorübergehend nicht erreichbar. Ein System, das sich ausschließlich auf Webhooks verlässt, bleibt in diesem Fall für immer bei „ich weiß es nicht“ stehen. Deshalb sollte der Webhook Ihr primärer Benachrichtigungskanal sein, nicht Ihre einzige Quelle der Wahrheit; ein periodischer Abgleich über die Status-Abfrage-API des PSP sollte immer als sekundäres Sicherheitsnetz bestehen.

Webhook (primär, schnell)
  + Periodische Statusabfrage (sekundär, langsam, aber garantiert)
  = selbst wenn der Webhook verloren geht, wird die Wahrheit früher oder später erfasst

Out-of-order: Ereignisse kommen ungeordnet an

Die Netzwerkebene garantiert nicht, dass Ereignisse in der gesendeten Reihenfolge ankommen. Eine „captured“-Benachrichtigung kann etwa vor der „authorized“-Benachrichtigung ankommen, die eigentlich vorausgehen sollte. Aktualisiert Ihr Handler die Zustandsmaschine, ohne Zeitstempel oder Versionsnummer des Ereignisses zu prüfen, müssen genau hier die Guards aus Teil zwei greifen.

Ankommt: payment.captured (t=2)
Ankommt: payment.authorized (t=1, aber später eingetroffen)
  → Guard: ein t=1-Ereignis kann einen bereits bei t=2 angekommenen Zustand nicht zurücksetzen, wird stillschweigend abgelehnt

Delayed: das Ereignis kommt verspätet an

Ein Webhook kann durch Warteschlangenbildung beim PSP oder Verarbeitungsverzögerung bei Ihnen Minuten zu spät ankommen. In diesem Fall muss Ihr Handler zwischen „jetzt“ und dem Zeitpunkt, „zu dem das Ereignis tatsächlich geschah“, unterscheiden; werden Geschäftsentscheidungen nach dem Verarbeitungszeitpunkt statt dem eigenen Zeitstempel des Ereignisses getroffen, wachsen Reihenfolgefehler.

Warum Sie schwere Arbeit nie synchron ausführen sollten

Ihr Webhook-Handler sollte außer Signaturprüfung, minimaler Validierung und einem Durable Write (Schreiben in die Inbox) nichts Schweres tun. Schritte wie Bestand reduzieren, einen Ledger-Eintrag öffnen oder eine Benachrichtigung senden sollten immer an einen separaten Hintergrundjob übergeben werden.

Webhook Handler (schnell, synchron)
  1. Signatur prüfen
  2. Minimale Schemaprüfung durchführen
  3. Ereignis in die Inbox schreiben (durable)
  4. 200 OK zurückgeben

Hintergrundjob (langsam, asynchron)
  5. Ereignis aus der Inbox lesen
  6. Die eigentlichen Geschäftsentscheidungen anwenden (Bestand, Ledger, Benachrichtigung)

Diese Trennung ist aus zwei Gründen entscheidend. Erstens setzen PSPs meist ein kurzes Timeout für die Webhook-Antwort (wenige Sekunden); überschreitet schwere Arbeit dieses Fenster, wertet der PSP die Anfrage als fehlgeschlagen und sendet sie erneut, was nur die Anzahl der Duplikate erhöht. Zweitens macht synchron ausgeführte schwere Arbeit Ihren Webhook-Handler von der Performance nachgelagerter Systeme abhängig (etwa eines langsamen Bestands-Services) — diese Abhängigkeit kann dazu führen, dass der Webhook-Aufruf selbst in ein Timeout läuft.

Die am häufigsten verwechselten Zuordnungen

❌ Ein Webhook ist die einzige, zuverlässige Quelle der Wahrheit
✓ Ein Webhook ist der primäre Benachrichtigungskanal; periodische Statusabfrage ist das sekundäre Sicherheitsnetz

❌ 200 zurückzugeben bedeutet, die Arbeit ist erledigt
✓ 200 bedeutet, das Ereignis wurde sicher empfangen; die Arbeit fertigzustellen ist ein separater, asynchroner Schritt

❌ Webhooks kommen immer in der gesendeten Reihenfolge an
✓ Reihenfolge wird nie garantiert; ohne Guards kann die Zustandsmaschine zurückdriften

❌ Signaturprüfung ist optional, wenn eine IP-Allowlist besteht
✓ Signaturprüfung ist die eigentliche Verteidigung gegen gefälschte oder manipulierte Webhooks

Checkliste zur Prüfung Ihres Webhook-Handlers

1. Prüft Ihr Webhook-Handler bei jeder Anfrage die Signatur, oder verlässt er sich nur auf eine IP-Allowlist?
2. Welche schwere Arbeit führt Ihr Handler synchron aus, bevor er das Ereignis in die Inbox schreibt?
3. Wenn ein Webhook nie ankommt — nach wie vielen Stunden oder Tagen merkt es Ihr System? Haben Sie einen Reconciliation-Job?
4. Können zwei ungeordnet eintreffende Webhooks Ihre Zustandsmaschine in einen ungültigen Zustand bringen? Haben Sie Ihre Guards getestet?
5. Wie lang ist das Webhook-Timeout-Fenster Ihres PSP, und wie viel davon nutzt Ihr Handler tatsächlich?

Beantworten Sie eine dieser fünf Fragen mit „nein, haben wir nicht geprüft“, ruht Ihre Webhook-Zuverlässigkeit wahrscheinlich auf einer ungetesteten Annahme.

Was aus diesem Teil bleiben sollte

1. Webhooks können Duplicate, Missing, Out-of-order und Delayed sein; Ihr Handler sollte alle vier als Standardfall annehmen, nicht als Ausnahme.
2. Signaturprüfung ist die eigentliche Verteidigungslinie gegen gefälschte Webhooks; eine IP-Allowlist allein reicht nicht.
3. Der Handler sollte schnell ACKen und schwere Arbeit an einen asynchronen Job übergeben; synchrone schwere Arbeit erhöht sowohl Timeout- als auch Duplikatrisiko.
4. Ein Webhook ist der primäre Kanal, nicht die einzige Quelle der Wahrheit; periodische Statusabfrage sollte immer als sekundäres Sicherheitsnetz bestehen.

Darauf zu vertrauen, dass ein Webhook „ankommen wird“, ist kein Design. Dafür zu entwerfen, dass er „vielleicht nicht ankommt, vielleicht doppelt ankommt, vielleicht ungeordnet ankommt“, ist es.