Obriym CRMObriym CRMCustomer flow workspace
KIFunktionenErste SchrittePreiseRoadmapIntegrationenBlog
DE
  • ukUkrainisch
  • enEnglisch
  • itItalienisch
  • deDeutsch
  • frFrançais
AnmeldenJetzt starten
KIFunktionenErste SchrittePreiseRoadmapIntegrationenBlogAnmeldenJetzt starten
Blog

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.

16. August 2026

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

Mehr erfahren

Erwähnte Integrationen

  • Monobank

    Beta

    Der Käufer bezahlt eine Rechnung, das CRM erhält von Monobank eine signierte Bestätigung, ordnet die Zahlung der Bestellung zu und informiert Ihr Team sofort. Kein manueller Abgleich von Kontoauszügen.

    Mehr erfahren
  • LiqPay

    Beta

    Eine auf Seiten von LiqPay bestätigte Zahlung löst eine Teambenachrichtigung aus und aktualisiert eine passende Bestellung im CRM.

    Mehr erfahren
  • WayForPay

    Verfügbar

    Das CRM prüft jedes Zahlungsergebnis, benachrichtigt Ihr Team und verknüpft die Zahlung mit einer bestehenden Bestellung. Ohne Treffer bleibt sie in einer übersichtlichen Abgleichwarteschlange.

    Mehr erfahren
  • Hutko

    Verfügbar

    Nach jeder Zahlung erfasst das CRM das Ergebnis, benachrichtigt Ihr Team und ordnet die Zahlung entweder einer vorhandenen Bestellung zu oder hält sie in einer übersichtlichen Abgleichswarteschlange bereit.

    Mehr erfahren

Beta: Beta: Die Verbindung ist bereits heute möglich; die Funktionen des Kanals werden noch ausgebaut.

Jetzt starten

Starten Sie mit einer echten Bestellung, nicht mit Demodaten.

Registrieren Sie sich, und Ihr Arbeitsbereich wird automatisch erstellt. Verbinden Sie einen Vertriebskanal, legen Sie ein Produkt an und nehmen Sie Ihre erste Bestellung oder Anfrage entgegen – das CRM zeigt Ihnen den nächsten Schritt selbst.

Kostenlos startenSo starten Sie, Schritt für Schritt
Obriym CRMObriym CRMCustomer flow workspace

Obriym CRM ist ein fokussierter Arbeitsbereich für Vertriebsteams und E-Commerce-Abläufe. Leads, Verkaufschancen, Bestellungen und Kundenbindung an einem Ort.

Ein Produkt von OBRIYM

  • crm@obriym.com
  • OBRIYM
  • Serhii Oberemchuk

Individual Entrepreneur Oberemchuk Serhii Oleksandrovych · Staatsregister 178752761226

Produkt

  • CRM für den Handel
  • KI
  • Funktionen
  • Erste Schritte
  • Preise
  • Vergleich
  • Blog
  • Roadmap
  • Integrationen
  • API-Referenz

Unternehmen

  • Über OBRIYM
  • Gründer
  • Kontakt
  • Roadmap

Entwickler

  • Für Entwickler
  • OpenAPI-Spezifikation
  • JS-Widget
  • API zur Lead-Erfassung
  • Bestell-API

©2026Obriym CRM von OBRIYM. Entwickelt für den produktiven Einsatz in Vertrieb und E-Commerce.

NutzungsbedingungenLeistungsbedingungenZahlung und RückerstattungenDatenschutzerklärungUnterauftragsverarbeiterDatenverarbeitungAnbieterangabenDatenlöschungPreiseAPI-Dokumentation