Analysen
Der Monobank-Acquiring-Webhook: ECDSA-Prüfung und warum der rohe Request-Body wichtig ist
Monobank signiert Webhooks mit ECDSA statt mit einem gemeinsamen HMAC-Secret. So funktioniert die Prüfung, so cachen Sie den öffentlichen Schlüssel, und das sind die beiden Fehler, bei denen die Prüfung „funktioniert“, aber nichts schützt.
Die meisten ukrainischen Zahlungsgateways signieren ihre Callbacks mit einem gemeinsamen Secret: Man nimmt das Händlerpasswort, baut nach einer dokumentierten Formel eine Zeichenfolge zusammen, hasht sie und vergleicht. Monobank macht es anders, und der Unterschied ist leicht zu übersehen – mit Folgen.
Monobank signiert den Webhook asymmetrisch: Es signiert mit einem privaten Schlüssel, und Sie prüfen mit dem ÖFFENTLICHEN Schlüssel, den Sie in einer separaten Anfrage abrufen. Es gibt überhaupt kein gemeinsames Secret. Das ist strikt bessere Sicherheit – selbst ein vollständiger Einbruch in Ihre Datenbank ermöglicht keine Fälschung eines Ereignisses –, verlangt aber zwei Dinge, die ein HMAC-Verfahren nicht braucht: den korrekten Umgang mit dem rohen Request-Body und das Caching des öffentlichen Schlüssels.
Der Vertrag
- Signatur
- Der Header x-sign – ECDSA über SHA-256, Base64-codiert
- Prüfschlüssel
- Der öffentliche Schlüssel des Händlers, GET /api/merchant/pubkey (erfordert Ihren X-Token)
- Was signiert wird
- Die exakten Bytes des Request-Body – nicht das Ergebnis des Parsens und erneuten Serialisierens
- Wo es ankommt
- Die Adresse, die Sie beim Erstellen der Rechnung in webHookUrl übergeben haben. Die offizielle API beschreibt keinen globalen Händler-Webhook.
- Zuordnung zur Bestellung
- merchantPaymInfo.reference – dort trägt Ihr Shop seine eigene Bestellkennung ein
- Beträge
- In der kleinsten Währungseinheit, nicht in ganzen Währungseinheiten
- Währung
- Numerischer ISO-4217-Code: 980 Hrywnja, 840 Dollar, 978 Euro
- Der Status expired
- Wird NICHT per Webhook zugestellt – das verfolgt, wer die Rechnung erstellt hat
Fehler eins: das JSON parsen, bevor die Signatur geprüft ist
Die Signatur deckt eine bestimmte Bytefolge ab. Wenn Ihr Framework den Body automatisch in ein Objekt parst und Sie es zur Prüfung wieder serialisieren, prüfen Sie andere Bytes. Reihenfolge der Schlüssel, Leerraum, Zahlendarstellung, Escaping von Nicht-ASCII-Zeichen: Jedes davon kann abweichen, und das tut es auch.
Das schlimmste Ergebnis ist hier nicht „nichts funktioniert“, sondern „funktioniert mit Testdaten und scheitert mit echten Daten“: Eine einfache Payload übersteht die Hin-und-zurück-Umwandlung zufällig, eine mit ukrainischen Zeichen im Namen des Käufers oder einem Bruchbetrag nicht.
Es gibt eine Regel: Den Body als rohen Text lesen, die Signatur dagegen prüfen und erst dann parsen. In einem Next.js-Route-Handler bedeutet das `await request.text()` vor jedem `request.json()` – der zweite Aufruf ist bei derselben Anfrage ohnehin nicht mehr möglich, die Reihenfolge ist hier also keine Stilfrage.
Fehler zwei: den öffentlichen Schlüssel bei jedem Webhook abrufen
Der öffentliche Schlüssel des Händlers ändert sich selten, während sein Abruf einen Roundtrip zu Monobank kostet und Ihr Ratenlimit verbraucht. Das pro Zahlung zu tun, ist ein sicherer Weg, unter Last auszufallen – genau dann, wenn viele Zahlungen eingehen.
Ihn für immer zu cachen ist aber ebenfalls falsch: Der Schlüssel kann neu ausgestellt werden, und dann nehmen Sie mit einem harten Cache bis zum nächsten Deployment keine Zahlungen mehr an.
Das funktionierende Schema ist Cache plus erneutes Laden bei Fehlschlag: den Schlüssel aus dem Cache nehmen und prüfen; schlägt die Prüfung fehl, den Schlüssel einmal neu lesen und erneut prüfen; schlägt sie weiter fehl, ablehnen. So heilt sich eine Schlüsselrotation von selbst, und ein Angreifer mit schlechter Signatur kostet Sie höchstens eine zusätzliche Anfrage.
Eine naheliegende Sache, die man oft falsch macht: Der öffentliche Schlüssel ist NICHT geheim. Verschlüsseln Sie ihn nicht im Ruhezustand. Er dient nur dazu, Signaturen zu prüfen, und ihn zu kennen, gewährt niemandem etwas. Verschlüsselt gehört der X-Token, mit dem Sie ihn abrufen.
Eine Prüfung, die wirklich schützt
- Prüfung fehlgeschlagen – die Anfrage ablehnen. Nicht „für alle Fälle“ protokollieren und weitermachen: Ein Webhook ohne gültige Signatur ist kein Ereignis, sondern ein Fremder, der Ihnen erzählt, Sie seien bezahlt worden.
- Der Schlüssel konnte nicht abgerufen oder der X-Token nicht entschlüsselt werden – ebenfalls ablehnen. Im Zweifel sperren: Dass eine Prüfung nicht verfügbar ist, ist kein Grund, dem Ungeprüften zu vertrauen.
- Vergleichen Sie auch die Händler-ID mit der Konfiguration des Adapters – dann kann ein Ereignis aus einem fremden Konto selbst mit gültiger Signatur nicht in Ihrem Arbeitsbereich landen.
- Machen Sie das Schreiben der Zahlung idempotent über die Rechnungs-ID: Die Bank darf dasselbe Ereignis zweimal zustellen, und das ist normales Verhalten, kein Fehler.
- Speichern Sie weder Kartennummer noch CVV. Betrag, Währung, Status und Rechnungs-ID genügen für den Abgleich – und was nicht in Ihrer Datenbank liegt, kann nicht abfließen.
Wohin mit einer Zahlung, zu der keine Bestellung gefunden wurde
Die Signatur stimmt, der Betrag ist da, und die Referenz passt zu nichts. Die häufigste Reaktion ist, das Ereignis zu verwerfen: 200 zurückgeben, nichts schreiben. Das ist die schlechteste Wahl, denn das Geld ist bereits eingegangen und hinterlässt in Ihrem System keine Spur.
Die Praxis, die man von Anfang an einbauen sollte: eine solche Zahlung als eigenen Datensatz ohne Bestellung speichern und in einem Zahlungsjournal als nicht zugeordnet markiert anzeigen. Ein Manager öffnet sie, sieht Betrag und Käufer und ordnet sie entweder einer bestehenden Bestellung zu oder legt daraus eine neue an. Das sind zehn Minuten Datenmodellierung, die eine ganze Klasse von Tickets des Typs „Wir haben bezahlt, und Sie sehen es nicht“ beseitigen.
Ein signierter Callback authentifiziert sich selbst
Die Versuchung, „zuerst einen Verbindungstest bestehen, dann Zahlungen annehmen“ zu verlangen, ist verständlich, hier aber überflüssig: Eine korrekte ECDSA-Signatur plus eine passende Händler-ID authentifiziert das Ereignis bereits vollständig. Ein Verbindungstest ist als Diagnose nützlich – zu welchem Konto gehört dieses Token? –, aber ihn zur Voraussetzung für echte Zahlungen zu machen, stellt ein Hindernis zwischen einen Kunden und sein Geld.
Häufig gestellte Fragen
Wie unterscheidet sich die Signatur von Monobank von LiqPay und WayForPay?
LiqPay und WayForPay nutzen ein gemeinsames Secret – SHA-1 beziehungsweise HMAC-MD5 über eine dokumentierte, zusammengesetzte Zeichenfolge. Monobank nutzt asymmetrisches ECDSA: Es gibt kein gemeinsames Secret, und Sie prüfen mit einem öffentlichen Schlüssel. Das Verfahren eines Anbieters darf also nie auf einen anderen übertragen werden; jeder Vertrag stammt aus der eigenen offiziellen Dokumentation des Anbieters.
Lässt sich ein Webhook für das gesamte Händlerkonto konfigurieren?
Die offizielle API beschreibt so etwas nicht. Die Adresse wird im Feld webHookUrl jeder Anfrage zum Erstellen einer Rechnung übergeben, es ist also Aufgabe Ihres Shops, sie mitzusenden.
Warum kommt der Status expired nie an?
Monobank stellt ihn nicht per Webhook zu. Wenn Sie von nie bezahlten Rechnungen wissen müssen, muss derjenige, der diese Rechnungen erstellt hat, ihren Status verfolgen.
Kommen Beträge in ganzen Hrywnja an?
Nein, in der kleinsten Einheit. 149,90 kommt als 14990 an. Die Währung kommt als numerischer ISO-4217-Code, nicht als Zeichenfolge „UAH“.
Kann das CRM über diese Integration eine Rückerstattung auslösen?
In unserer Umsetzung nein, und zwar bewusst. Der Adapter nimmt Zahlungsstatus entgegen; das Erstellen und Stornieren von Rechnungen, Rückerstattungen und jegliche Abbuchungen bleiben bei Monobank und dem Shop. Eine Integration, die Geld bewegen kann, braucht eine andere Vertrauensstufe und ein anderes Audit.
Eine fertige Integration statt einer eigenen
Obriym CRM nimmt signierte Webhooks von Monobank, LiqPay, WayForPay und Hutko in einem Zahlungsjournal entgegen – mit Idempotenz, Zuordnung zu Bestellungen und einer Benachrichtigung an Ihr Team.
Kostenlos testen