Krypto-Zahlungs-Webhooks: Funktionsweise und Aufbau

Ein Krypto-Zahlungs-Webhook ist eine HTTP-Anfrage, die ein Blockchain-Dienst an Ihren Server sendet, wenn on-chain etwas passiert. Ein typisches Beispiel ist eine Einzahlung auf der Adresse eines Kunden. Statt alle paar Sekunden beim Netzwerk nachzufragen, ob eine Zahlung eingegangen ist, geben Sie dem Anbieter eine URL, und er ruft Sie auf.

Für den Produktivbetrieb brauchen Sie vier Dinge: einen öffentlichen Endpunkt, eine Signaturprüfung, eine idempotente Verarbeitung doppelter Events und eine Rückfalllösung für verpasste Zustellungen. Dieser Leitfaden behandelt jeden davon.

TL;DR

• Ein Webhook schiebt ein Event an Ihren Server, sobald eine Zahlung oder ein Wallet-Ereignis eintritt. Sie verzichten so auf ständiges Polling und die Last, die es erzeugt.
• Prüfen Sie die Signatur jeder Anfrage, bevor Sie einem Feld darin vertrauen. Bei Chaingateway deckt die Signatur nur die Transaktions-ID ab. Prüfen Sie Betrag und Empfänger deshalb selbst.
• Antworten Sie schnell mit einem 2xx-Status und erledigen Sie die eigentliche Arbeit in einem Hintergrundjob.
• Behandeln Sie jedes Event als möglicherweise wiederholt. Speichern Sie Event-IDs und machen Sie Bestellaktualisierungen idempotent.
• Betreiben Sie einen langsamen Abgleichsjob für offene Zahlungen. Chaingateway wiederholt fehlgeschlagene Benachrichtigungen nicht von selbst. Eine verpasste Zustellung würde sonst eine Bestellung hängen lassen.

Was sind Krypto-Zahlungs-Webhooks?

Ein Webhook ist ein Rückruf. Sie registrieren eine URL und sagen dem Anbieter, welche Events Sie interessieren. Tritt eines ein, sendet der Anbieter eine POST-Anfrage mit einem JSON-Body, der es beschreibt. Bei Krypto-Zahlungen sind diese Events meist eine eingehende Überweisung an eine überwachte Adresse, eine ausgehende Überweisung oder eine Token-Überweisung über einen Contract.

Die Alternative ist Polling. Ihr Server ruft in einem Takt eine API auf und vergleicht das Ergebnis mit dem letzten Mal. Polling ist einfach zu schreiben und im Betrieb verschwenderisch. Jede Anfrage, die nichts Neues liefert, kostet Rate-Limit, Rechenzeit und Latenz. Die Verzögerung zwischen Zahlung und Reaktion entspricht Ihrem Intervall. Mit mehreren Chains und tausenden Kundenadressen vervielfacht sich die Zahl der Aufrufe schnell.

Webhooks kehren die Richtung um. Der Anbieter überwacht die Chain, gleicht Transaktionen mit den Adressen ab, die Sie abonniert haben, und benachrichtigt Sie einmal. Die Reaktionszeit sinkt auf Sekunden, und Ihre eigene Infrastruktur bleibt untätig, bis es etwas zu tun gibt. Die ausführlichere Begründung für Einzahlungen finden Sie in wie Webhooks Einzahlungen automatisch verarbeiten.

Webhooks und Polling im Überblick

Die letzte Zeile ist die praktische Antwort. Webhooks sollten das Hauptsignal sein. Polling sollte eine langsame Rückversicherung sein, die nur noch offene Zahlungen prüft. Prüfen Sie nur Rechnungen, die noch offen sind. So findet man eine verpasste Zustellung innerhalb von Minuten, und die Zahl der Anfragen bleibt niedrig.

Wie erkennt ein Webhook eine Krypto-Zahlung?

Die Seite des Anbieters sehen Sie nicht. Sie zu verstehen, erklärt aber die meisten Verhaltensweisen, auf die Sie beim Testen stoßen.

1. Abonnement. Sie legen eine Wallet an oder registrieren eine Adresse und registrieren dafür über die API des Anbieters einen Webhook. Das Abonnement enthält Ihre Callback-URL und Filter wie Absender, Empfänger, Contract-Adresse und Transaktionstyp.
2. Überwachung. Der Anbieter betreibt Nodes für jede unterstützte Chain und liest jeden neuen Block. Jede Transaktion wird mit den Abonnements abgeglichen. Bei Token geschieht das zusätzlich mit den Transfer-Logs des Contracts.
3. Dekodierung. Rohe Chain-Daten sind nicht gut lesbar. Ein Token-Transfer auf Ethereum ist ein kodierter Log-Eintrag, und Bitcoin kennt Ein- und Ausgaben statt Absender und Empfänger. Der Anbieter macht daraus einen lesbaren Payload.
4. Zustellung. Der Anbieter sendet den Payload an Ihre URL. Antwortet Ihr Server nicht mit einem Erfolgscode, hängt das weitere Vorgehen vom Anbieter ab. Einige wiederholen nach einem Zeitplan. Chaingateway wiederholt nicht von selbst. Der Dienst listet fehlgeschlagene Benachrichtigungen auf, und Sie fordern das erneute Senden für jede einzelne an.

Eine Chaingateway-Benachrichtigung enthält die Felder id, webhook_id, from, to, blocknumber, datetime, type, contractaddress, tokenid, txid und amount. Dieselben Feldnamen gelten auf Ethereum, BNB Smart Chain, Polygon, Arbitrum und Tron. Bitcoin-Webhooks filtern nur nach Absender und Empfänger. Solana hat keine Webhooks. Token-Standards wie ERC-20, BEP-20 und TRC-20 werden unterstützt. Das ist wichtig, denn die meisten realen Zahlungen sind Stablecoin-Transfers und keine native Währung.

Welche Events lohnt es zu abonnieren?

Fangen Sie eng an. Bei Chaingateway wird ein Webhook durch Filter definiert. Jeder Event-Typ entspricht deshalb einer Kombination von Filtern:

• Eine eingehende Überweisung an eine Einzahlungsadresse eines Kunden nutzt to. Das ist das Kernereignis, um ein Konto gutzuschreiben oder eine Rechnung als bezahlt zu markieren.
• Eine ausgehende Überweisung nutzt from, zum Beispiel um zu sehen, wann eine Auszahlung oder ein Sweep die Chain erreicht.
• Eine Token-Überweisung nutzt type (etwa ERC20 oder TRC20) mit einer contractaddress.
• Eine NFT-Überweisung nutzt das Feld token_id mit dem Typ ERC721 oder TRC721.
• Das optionale Feld reference mit bis zu 255 Zeichen verknüpft einen Webhook mit einer Bestellung oder einem Kunden in Ihrem System.

Eine Benachrichtigung meldet nur, dass eine Transaktion gesehen wurde, die zum Filter passt. Ob Sie sie als endgültig behandeln, entscheiden Sie selbst. Der Abschnitt zur Bestätigungstiefe erklärt das.

Unser Beitrag zu Polygon-Webhooks ohne Polling zeigt, wie das auf einer einzelnen Chain aussieht.

Wie richten Sie einen Webhook-Endpunkt ein und verarbeiten ihn?

Der Endpunkt ist eine gewöhnliche HTTPS-Route auf Ihrem Server. Der Unterschied zwischen einer Demo und einem Produktiv-Handler liegt in einigen Gewohnheiten.

Anforderungen an den Endpunkt

Die URL muss über HTTPS aus dem öffentlichen Internet erreichbar sein. Localhost-Adressen und private Netze können keine Aufrufe empfangen. Während der Entwicklung brauchen Sie deshalb einen Tunnel, der Ihren lokalen Port nach außen führt. Halten Sie die Route ausschließlich für Webhooks reserviert. Akzeptieren Sie nur POST und setzen Sie keine Login-Bildschirme oder CSRF-Middleware davor, die eine Maschinenanfrage abweisen würde.

Der Handler sollte schnell antworten. Die übliche Empfehlung, etwa in der Stripe-Webhook-Dokumentation, lautet, rasch einen Erfolgscode zurückzugeben, bevor komplexe Logik laufen kann, die ein Timeout auslösen könnte. Erfolgreich heißt ein 2xx-Status laut RFC 9110. Dieselbe Regel gilt für Krypto-Events. Wenn Sie eine Datenbank aktualisieren, eine E-Mail senden und ein Buchhaltungssystem aufrufen, bevor Sie antworten, kann ein langsamer nachgelagerter Dienst dazu führen, dass der Anbieter die Zustellung als fehlgeschlagen wertet.

Ein zuverlässiges Muster sieht so aus:

1. Lesen Sie den Request-Body.
2. Prüfen Sie die Signatur.
3. Schreiben Sie das Event mit seiner ID in eine Warteschlange oder eine Event-Tabelle.
4. Antworten Sie mit 200.
5. Lassen Sie einen Worker das eingereihte Event verarbeiten.

Wie prüfen Sie Webhook-Signaturen?

Wer Ihre URL findet, kann JSON dorthin senden. Wenn Ihr Handler ein Konto gutschreibt, weil eine Anfrage sagt, eine Einzahlung sei eingegangen, ist eine gefälschte Anfrage ein Diebstahl. Die Signaturprüfung schließt diese Tür.

Das übliche Verfahren ist HMAC, definiert in RFC 2104. Der Anbieter berechnet einen Hash mit einem Geheimnis, das nur Sie und er kennen, und sendet das Ergebnis im Header. Sie berechnen den Hash neu und vergleichen. Drei Details führen häufig in die Irre:

• Wissen Sie, was signiert wird. Viele Anbieter signieren den gesamten Request-Body. Dann müssen Sie gegen die Originalbytes prüfen und nicht gegen neu serialisiertes JSON. Chaingateway signiert nur die Transaktions-ID.
• Vergleichen Sie in konstanter Zeit. Nutzen Sie die sichere Vergleichsfunktion Ihrer Sprache und keinen einfachen Gleichheitsvergleich.
• Prüfen Sie einen Zeitstempel, wenn das Verfahren einen liefert. Das Zurückweisen alter Zeitstempel begrenzt das Wiederabspielen eines mitgeschnittenen Requests. Das Verfahren von Chaingateway hat keinen Zeitstempel. Deduplizieren Sie deshalb über die Transaktions-ID.

Chaingateway sendet die Signatur im Header X-Signature, sobald Sie in Ihrem Profil ein persönliches Secret gesetzt haben. Der Wert ist die Base64-kodierte HMAC-SHA256 des Feldes txid, geschlüsselt mit diesem Secret. Der Leitfaden zur Signaturprüfung enthält einen funktionierenden Node.js-Handler. Die Dokumentation enthält Versionen für Python, Java und PHP. Da nur die txid signiert ist, belegt eine gültige Signatur nicht, dass amount oder to unverändert sind. Prüfen Sie diese Werte gegen Ihre Rechnung oder gegen die Chain, bevor Sie etwas gutschreiben.

Speichern Sie das Secret in einer Umgebungsvariable oder einem Secrets-Manager, nie im Repository. Generieren Sie es neu, falls es jemals in einem Log auftaucht. Ein neu generiertes Secret wirkt sofort.

Wie behandeln Sie Wiederholungen, Duplikate und langsame Bestätigungen?

Netzwerke fallen aus, und Deployments starten Server neu. Ihr Handler wird irgendwann dasselbe Event zweimal sehen, etwa nach einem erneuten Senden, und manchmal kommen Events außer der Reihe. Planen Sie das von Anfang an ein.

Verarbeitung idempotent machen

Jedes Event trägt etwas, das es identifiziert. In einer Chaingateway-Benachrichtigung ist das die txid zusammen mit der webhook_id. Speichern Sie diese Kennung mit einer eindeutigen Constraint, bevor Sie handeln. Schlägt das Einfügen fehl, weil der Schlüssel schon existiert, haben Sie das Event bereits gesehen. Sie können dann mit 200 antworten, ohne etwas zu tun.

Machen Sie danach die Geschäftsaktion selbst gefahrlos wiederholbar. „Rechnung 1042 auf bezahlt mit Transaktion X setzen“ ist idempotent. „50 zum Guthaben addieren“ ist es nicht. Bevorzugen Sie die erste Form oder koppeln Sie die Guthabenänderung in einer einzigen Datenbanktransaktion an den eindeutigen Event-Datensatz.

Bestätigungstiefe beachten

Eine Transaktion, die in einem Block auftaucht, ist nicht dasselbe wie eine Zahlung, gegen die Sie Ware ausliefern können. Chains unterscheiden sich darin, wie schnell ein Block unwahrscheinlich wird, rückgängig gemacht zu werden. Die richtige Schwelle hängt von Betrag und Vermögenswert ab. Legen Sie eine Regel je Chain und je Bestellgröße fest und speichern Sie den Status jeder Zahlung: erkannt, bestätigend, bestätigt, fehlgeschlagen. Der Webhook, der die Erkennung meldet, sollte eine Bestellung auf „Zahlung gesehen“ setzen, nicht auf „erfüllt“.

Unterzahlungen, Überzahlungen und falsche Token

Kunden senden häufiger den falschen Betrag, als man erwartet. Ihr Handler sollte den eingegangenen Betrag und Vermögenswert mit der Rechnung vergleichen und verzweigen: exakt, zu wenig, zu viel oder ein unerwarteter Token. Legen Sie im Voraus fest, ob Sie die Differenz automatisch gutschreiben, zur Prüfung halten oder erstatten. Eine dekodierte Nutzlast mit Vermögenswert und Betrag als getrennten Feldern macht diesen Vergleich zu wenigen Zeilen Code und nicht zu einer Parsing-Aufgabe.

Ein Sicherheitsnetz einziehen

Eine Zustellung kann fehlschlagen, und Chaingateway wiederholt sie nicht. Fehlgeschlagene Benachrichtigungen erscheinen unter GET /api/v2/<chain>/webhooks/notifications/failed. Sie senden jede mit POST /api/v2/<chain>/webhooks/notifications/{id}/retry erneut. Richten Sie einen geplanten Job ein, der alle paar Minuten diese Liste prüft und Rechnungen anschaut, die länger als vertretbar offen sind. Findet er eine Zahlung, die Ihr Webhook nie gemeldet hat, schickt er sie durch denselben Verarbeitungsweg. Ein gemeinsamer Codepfad für beide Quellen bedeutet einen gemeinsamen Satz von Fehlern.

Wie testen und überwachen Sie einen Webhook-Endpunkt?

Bauen Sie Vertrauen in Schichten auf:

1. Lokaler Test. Schreiben Sie ein kleines Skript, das einen Beispiel-Payload mit Ihrem Test-Secret signiert und an Ihren Endpunkt sendet. Prüfen Sie, dass eine gültige Signatur durchgeht und eine geänderte txid scheitert.
2. Testnetz-Lauf. Legen Sie eine Wallet in einem Testnetz mit dem Header X-Network: testnet an, registrieren Sie einen Webhook und senden Sie eine kleine Überweisung von einem Faucet. Dann sehen Sie die echte Abfolge der Events, einschließlich der Verzögerung bis zur Benachrichtigung. Diese Verzögerung lernen Sie aus keinem Beispiel-Payload.
3. Duplikat-Übung. Senden Sie dasselbe gültige Event fünfmal. Ihre Rechnung sollte sich einmal ändern, und Ihre Logs sollten vier übersprungene Duplikate zeigen.
4. Fehler-Übung. Lassen Sie Ihren Handler absichtlich mit 500 antworten. Finden Sie dann die Benachrichtigung in der Liste der fehlgeschlagenen, stellen Sie den Handler wieder her und senden Sie sie erneut. Sie sollte genau einmal verarbeitet werden.

Protokollieren Sie im Betrieb jede eingehende Event-ID, das Ergebnis der Prüfung, das Verarbeitungsergebnis und die benötigte Zeit. Lösen Sie Alarm bei drei Dingen aus: Signaturfehler (ein falsch konfiguriertes Secret oder ein Angreifer), eine wachsende Warteschlange (Worker kommen nicht hinterher) und Rechnungen, die deutlich länger als üblich offen sind (stille Zustellungsprobleme).

Häufige Probleme und ihre üblichen Ursachen:

Wie empfangen Sie Zahlungsevents mit Chaingateway?

Sie legen einen Webhook mit einer Anfrage an POST /api/v2/<chain>/webhooks an. Das Beispiel registriert einen TRC20-Einzahlungsmonitor mit einer Referenz zu Ihrer Bestellung:

curl -X POST https://app.chaingateway.io/api/v2/tron/webhooks \
  -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "TWrTTVizHkF3LxTiWE9vCnhWC7CBpNXe22",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "type": "TRC20",
    "url": "https://shop.example.com/hooks/crypto",
    "reference": "order-10442"
  }'

Chaingateway Webhooks arbeiten mit der Blockchain API zusammen. Das Event, das Ihnen eine eingegangene Einzahlung meldet, und der Aufruf, der sie weitersendet, laufen so unter einem Konto.

Die Tarife stehen auf der Preisseite. Plus kostet 49 Euro im Monat, Pro 99 Euro, Premium 249 Euro und Enterprise 499 Euro. Bei jährlicher Abrechnung sind es 490, 990, 2.490 und 4.990 Euro im Jahr. Die 7-tägige Testphase braucht weder Karte noch KYC. Sie können Ihren Endpunkt also einrichten und zuerst die oben beschriebenen Übungen durchführen.

Quellen

• Webhooks, Stripe documentation
• HMAC: Keyed-Hashing for Message Authentication, RFC 2104
• Successful 2xx status codes, HTTP Semantics, RFC 9110

Empfohlen

• Wie Webhooks Einzahlungen automatisch verarbeiten
• Webhooks vs. WebSockets für Entwickler: Muster aus Erfassung, Warteschlange und Verteilung
• Polygon-Webhooks: Echtzeit-Events on-chain ohne Polling
• Echtzeit-Krypto-Alarme: Preis-Apps vs. Webhook-Alarme