Krypto-Payment-Webhooks: Events, Sicherheit und zuverlässige Auftragsabwicklung

Krypto-Payment-Webhooks sind HTTP-Anfragen, die ein Payment-Gateway an deinen Server sendet, sobald sich der Status einer Rechnung ändert: Überweisung erkannt, on-chain bestätigt, unter- oder überzahlt oder abgelaufen. Dein Handler prüft die Signatur, aktualisiert die Bestellung und stößt die Auslieferung an. Weil Krypto-Zahlungen asynchron eintreffen – Minuten nachdem der Kunde deine Seite verlassen hat –, ist der Webhook die maßgebliche Quelle, nicht der Browser.

Dieser Leitfaden konzentriert sich auf die Webhook-Seite einer Integration: welche Events kommen, wie du sie prüfst, wie die Verarbeitung sicher bleibt, wenn dasselbe Event zweimal ankommt, und wie du testest und überwachst. Zum Erstellen von Rechnungen siehe unseren Leitfaden zur Integration der Krypto-Payment-API.

Warum Webhooks statt Polling oder Redirects?

• Redirects sind kein Beweis — dass der Kunde auf deine Dankeseite zurückkehrt, sagt nichts darüber, ob Geld angekommen ist.
• Polling ist verschwenderisch — alle paar Sekunden für jede offene Rechnung die API abzufragen, skaliert nicht und hinkt trotzdem hinterher.
• Webhooks sind Push — das Gateway meldet sich, sobald sich etwas ändert, mit einer prüfbaren Signatur.

Die Events, die du erhältst

Das sind die Event-Namen von mistKET. Andere Gateways nutzen ähnliche Status unter anderen Namen; bilde sie an einer zentralen Stelle auf deine Bestellstatus ab.

Die Signatur prüfen

Jeder kann einen POST an eine öffentliche URL schicken – deshalb muss jeder Webhook authentifiziert werden. mistKET signiert jede Zustellung mit HMAC-SHA256 und sendet diese Header:

• X-Mistket-Event — der Event-Name.
• X-Mistket-Timestamp — Unix-Zeit, die in die Signatur einfließt.
• X-Mistket-Signature — sha256= gefolgt vom HMAC über {timestamp}.{raw body} mit deinem Webhook-Secret.
• X-Mistket-Delivery — eine Zustell-ID fürs Logging.

1. Rohen Body lesen — vor jedem JSON-Parsing, denn erneutes Kodieren verändert die Bytes.
2. HMAC neu berechnen — über Zeitstempel, Punkt und rohen Body, mit deinem Webhook-Secret.
3. In konstanter Zeit vergleichen — mit hash_equals, hmac.compare_digest oder crypto.timingSafeEqual.
4. Alte Zeitstempel ablehnen — etwa alles über fünf Minuten, um Replays zu blockieren.
5. Erst dann parsen und handeln — und zügig mit 2xx antworten.

Die Konstruktion folgt dem Standardmuster HMAC; halte das Secret auf dem Server und tausche es, falls es je abfließt.

Callback-URL wählen und schützen

Nutze einen eigenen HTTPS-Pfad wie /webhooks/mistket, getrennt von deinen normalen Seiten, und übergib ihn beim Erstellen jeder Rechnung als Callback-URL. Nimm ihn von CSRF-Schutz, Caching und Weiterleitungen aus; ein 301-Redirect oder eine gecachte Antwort ist ein häufiger Grund für still scheiternde Webhooks. Verlange kein Session-Cookie – das Gateway ist kein eingeloggter Nutzer, die Authentifizierung ist die HMAC-Signatur. Logge schließlich jede Zustellung mit Event, Bestellnummer und Antwortcode, damit du „Ist der Webhook angekommen?“ in Sekunden beantworten kannst.

Idempotenz: Dasselbe Event kann zweimal kommen

Läuft dein Endpoint in einen Timeout oder gibt einen Fehler zurück, wiederholt das Gateway die Zustellung stundenlang mit wachsenden Abständen. Auch Netzwerkstörungen können ein bereits verarbeitetes Event erneut liefern. Dein Handler muss daher idempotent sein:

• Bestellnummer als Schlüssel — suche die Bestellung, auf die die Rechnung verweist.
• Aktuellen Status prüfen — ist die Bestellung bereits ausgeliefert, bestätigen und nichts weiter tun.
• Transaktion oder Lock nutzen — damit zwei parallele Zustellungen nicht beide ausliefern.
• Zustell-ID speichern — hilfreich beim Debuggen von Duplikaten.

Bestellstatus um Events herum gestalten

Eine einfache Zustandsmaschine verhindert die meisten Fehler: offen → wird bestätigt (bei paid) → bezahlt (bei confirmed) → ausgeliefert, mit Seitenzweigen für unterzahlt und abgelaufen. Erlaube nur Übergänge nach vorn. Ein invoice.paid, das nach invoice.confirmed eintrifft, darf eine Bestellung nie zurückstufen. Späte Zahlungen auf abgelaufene Rechnungen sollten einen Prüfdatensatz erzeugen, statt die Bestellung still wieder zu öffnen.

Die unangenehmen Fälle

• Unterzahlt — nenne dem Kunden den exakten Fehlbetrag und dass er ihn an dieselbe Zahlungsseite senden kann; Teilzahlungen werden addiert.
• Überzahlt — ausliefern, dann laut deiner Regel über Guthaben oder Rückerstattung entscheiden.
• Abgelaufen — Bestand freigeben und eine neue Rechnung anbieten, falls der Kunde noch kaufen möchte.
• Falsches Netzwerk — das löst der Support, nicht der Code; zeige das Netzwerk im Checkout deutlich an, um es zu vermeiden.

Testen und Monitoring

1. Test-Endpoint bereitstellen — über HTTPS, mit Logging von Headern und rohen Bodys.
2. Jedes Event auslösen — paid, confirmed, underpaid, overpaid und expired mit kleinen echten Zahlungen.
3. Eine Zustellung wiederholen — prüfen, dass der Handler das Duplikat ignoriert.
4. Signatur brechen — ein Byte ändern und sicherstellen, dass die Anfrage abgelehnt wird.
5. Zustell-Logs beobachten — der Händlerbereich zeigt jeden Versuch, Antwortcode und Transaktions-Hash.
6. Bei Fehlern alarmieren — ein Anstieg von Nicht-2xx-Antworten bedeutet unerledigte Bestellungen.

Bots und bezahlte Communities folgen demselben Muster; wie das in einen Chat passt, zeigt Krypto-Zahlungen in einem Telegram-Bot annehmen.

Webhooks mit mistKET

mistKET sendet HMAC-signierte Webhooks für jeden Rechnungsstatus, wiederholt fehlgeschlagene Zustellungen mit wachsenden Abständen und zeigt im Händlerbereich Zustell-Logs, erwartete und erhaltene Beträge sowie Transaktions-Hashes. API-Anfragen werden auf dieselbe Weise signiert, sodass eine Hilfsfunktion beide Richtungen abdeckt.

Sieh dir Anfrage- und Webhook-Beispiele im Entwicklerbereich an, prüfe die Preise und verwalte Schlüssel über den Händler-Login. Für Zugang bewirb dich auf Telegram unter @mistnetwork.