Krypto-Zahlungs-Webhook: id und status verarbeiten
Anleitung zum Krypto-Zahlungs-Webhook: den finalen Status als POST mit id und status empfangen, den Header x-api-key prüfen und Bestellungen aktualisieren.
Ein Krypto-Zahlungs-Webhook teilt Ihrem Backend den finalen Status einer Zahlung mit. Bei Qvard ist das ein POST mit Ihrer Bestell-ID und dem Status, sodass die Bestelllogik aktualisiert wird, ohne die API abzufragen.
Was der Webhook sendet
Qvard ruft Ihre Webhook-URL mit einer POST-Anfrage auf. Der Body enthält die id, die Sie beim Anlegen der Zahlung gesendet haben, und den Status, zum Beispiel paid. Die Anfrage trägt Ihr Token x-api-key im Header.
Den Header x-api-key prüfen
Bevor Sie der Nachricht vertrauen, vergleichen Sie den Header x-api-key mit dem Token Ihres Kontos. Lehnen Sie Anfragen ohne diesen Header ab, damit niemand eine Bestellung als bezahlt markieren kann, indem er Ihren Endpoint direkt aufruft.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Die Bestellung über die id aktualisieren
Suchen Sie die Bestellung über die id aus dem Body und ändern Sie ihren Zustand gemäß dem Status. Markieren Sie eine Bestellung nur dann als bezahlt, wenn der Status paid ist, und ignorieren Sie Status, die Ihr System nicht verarbeitet.
Den Handler wiederholungssicher machen
Derselbe Webhook kann mehr als einmal eintreffen. Speichern Sie bereits verarbeitete id und Status und tun Sie nichts, wenn das Ereignis schon behandelt wurde. Antworten Sie mit einem Erfolgscode, nachdem die Änderung gespeichert ist.
Schnell antworten, langsame Arbeit einreihen
Bestätigen Sie den Webhook, sobald die Bestellung gespeichert ist. Senden Sie E-Mails, Rechnungen und Lageraufrufe aus einem Hintergrundjob, damit ein langsamer Schritt nie zu einem Timeout führt.
Mit einer Demo-Rechnung testen
Legen Sie eine Demo-Rechnung an, bezahlen Sie sie auf der gehosteten Seite und beobachten Sie, wie Ihr Endpoint den Webhook empfängt, bevor Sie in den Produktivbetrieb gehen.
FAQ
Was ist der Unterschied zwischen der API-Antwort und dem Webhook?
Die API-Antwort bestätigt, dass die Zahlung angelegt wurde, und liefert eine redirectUrl. Nur der Webhook meldet den finalen Status der Zahlung.
Was passiert, wenn mein Endpoint nicht erreichbar ist?
Die Zustellung wird wiederholt, Ihr Handler muss also wiederholungssicher sein. Prüfen Sie Ihre Logs regelmäßig und gleichen Sie Bestellungen ab, die offen geblieben sind.
Kann ich einem Webhook ohne x-api-key vertrauen?
Nein. Prüfen Sie den Header x-api-key immer, bevor Sie eine Bestellung ändern.
Welche Status sollte ich behandeln?
Behandeln Sie paid für erfolgreiche Zahlungen und betrachten Sie andere Status als Information. Die API-Dokumentation listet alle Werte auf.
