Webhooks für Kryptozahlungen: jeden Auftrag nur einmal erfüllen

Eine gültige Zahlungsbenachrichtigung darf nicht dazu führen, dass derselbe Auftrag zweimal erfüllt wird. Webhooks für Kryptozahlungen brauchen zwei getrennte Schutzmechanismen: Sie müssen prüfen, wer das Ereignis gesendet hat, und anschließend sicherstellen, dass eine Wiederholung seiner geschäftlichen Wirkung unbedenklich ist. Die Signatur beantwortet die erste Frage. Idempotenz beantwortet die zweite.

Dieser Leitfaden richtet sich an Entwickler, die einmalige digitale Käufe, Lizenzen oder Kontogutschriften mit Yolfi verbinden. Er erläutert das native Webhook-Format und einen empfohlenen Anwendungsentwurf, keinen fertigen Dienst zur Auftragserfüllung. Bei Abonnements hängt der Zugang auch vom Lebenszyklus des Abonnements ab; übertragen Sie eine Regel für Einmalaufträge nicht auf jede Verlängerung.

Warum auch ein echter Webhook ein Duplikat verursachen kann

Ein Empfänger kann ein Ereignis erfolgreich speichern, während seine HTTP-Antwort verloren geht. Der Absender versucht es daraufhin erneut. Ebenso kann Ihr Verarbeitungsprozess nach der Freischaltung des Zugangs abstürzen, bevor er den Abschluss vermerkt. Keine dieser Situationen bedeutet, dass der Kunde ein zweites Mal bezahlt hat.

Yolfis Referenz zu Webhook-Ereignissen beschreibt eine mindestens einmalige Zustellung und unabhängige Wiederholungsversuche für mehrere Endpunkte. Planen Sie ein, dass dasselbe Ereignis erneut eintrifft, möglicherweise noch während die erste Zustellung verarbeitet wird. Verlassen Sie sich weder auf einen bestimmten Zeitplan für Wiederholungen noch darauf, dass Benachrichtigungen Ihre Anwendung immer in der Reihenfolge ihrer Erstellung erreichen.

Halten Sie drei Identitäten auseinander:

Die Erkennung doppelter Ereignisse allein reicht nicht aus: Zwei erfolgreiche Zahlungsversuche für einen Auftrag können unterschiedliche Ereignis-IDs haben. Ein Schutz auf Auftragsebene verhindert eine zweite Lizenz oder Gutschrift, während der zusätzliche Zahlungseingang separat geprüft wird.

Prüfen Sie die unveränderte Anfrage, bevor Sie ihren Feldern vertrauen

Befolgen Sie die aktuellen Yolfi-Anweisungen zur Signaturprüfung. Native Anfragen verwenden X-Yolfi-Signature: einen Base64-kodierten HMAC-SHA256 über den unveränderten Anfragekörper, berechnet mit dem Signaturgeheimnis dieses Endpunkts. Der API-Schlüssel der Organisation ist nicht das Webhook-Geheimnis.

Erfassen Sie den ursprünglichen Anfragekörper, bevor JSON-Middleware ihn verändert. Berechnen Sie die Signatur und vergleichen Sie sie mit einer Vergleichsfunktion mit konstanter Laufzeit; weisen Sie fehlende oder fehlerhaft formatierte Signaturen ab, ohne Geschäftsaktionen auszuführen. Speichern Sie Signaturgeheimnisse in einer Geheimnisverwaltung oder einer geschützten Umgebungskonfiguration, niemals in Quelldateien oder Protokollen der Kundenbetreuung.

Erst nach der Prüfung sollten Sie die Nutzdaten einlesen und validieren. Verwenden Sie die id der signierten Nutzdaten zur Duplikaterkennung. X-Yolfi-Event-ID ist eine Hilfskopie und kein separat signierter Wert; falls Sie diesen Header nutzen, verlangen Sie Übereinstimmung mit der ID in den Nutzdaten. Binden Sie den empfangenden Endpunkt an die erwartete Organisation und prüfen Sie orgId, sofern vorhanden. Vom Benutzer übermittelte Metadaten dürfen nicht über die Mandantenberechtigung entscheiden.

Eine gültige Signatur macht eine alte Zustellung nicht zu einer neuen. Bereits verarbeitete Ereignis-IDs müssen weiterhin aufbewahrt werden. Yolfis dokumentierte Signatur ist keine zeitstempelbasierte Aktualitätsprüfung; behaupten Sie daher nicht, dass die HMAC-Prüfung allein das erneute Einspielen alter Anfragen verhindert.

Erst speichern, dann bestätigen, anschließend asynchron verarbeiten

Verwenden Sie einen dauerhaften Eingangsspeicher: eine Anwendungstabelle, die ein authentifiziertes Ereignis und seinen Verarbeitungsstatus festhält. Fügen Sie das Ereignis unter einer Eindeutigkeitsbedingung der Datenbank ein, statt zunächst separat zu prüfen, ob es vorhanden ist, und es danach ungeschützt einzufügen. Gleichzeitige Anfragen können beide diese Prüfung bestehen.

Geben Sie nach der dauerhaften Annahme zügig 200 OK zurück, auch wenn ein authentifiziertes Duplikat bereits gespeichert ist. Schlägt die Speicherung fehl, bestätigen Sie das Ereignis nicht als angenommen. Eine schnelle Antwort mit einer anschließenden Aufgabe im Arbeitsspeicher ist nicht dauerhaft: Bei einem Neustart kann die einzige von Ihrer Anwendung aufbewahrte Kopie verloren gehen.

Ein Verarbeitungsprozess kann anschließend das gespeicherte Ereignis laden, seine Zuordnung zum Auftrag prüfen und den geschäftlichen Zustandswechsel durchführen. Halten Sie fehlgeschlagene Aufgaben mit Wiederholungszähler, nächster Maßnahme und einer für Warnmeldungen verantwortlichen Person sichtbar. Bewahren Sie nur notwendige Nutzdaten in einem zugriffsbeschränkten Speicher auf; Ereigniskörper können Kundendaten enthalten.

Erfüllen Sie Aufträge nur nach Bestätigung und korrekter Zuordnung

Der Yolfi-Webhook-Leitfaden nennt payment.confirmed als primären Auslöser für die Auftragserfüllung. invoice.created bedeutet, dass eine Rechnung erstellt wurde, nicht dass der Kunde bezahlt hat. Eine Browserweiterleitung oder ein Bildschirmfoto ersetzt keine geprüfte serverseitige Bestätigung.

Ordnen Sie das Ereignis einem serverseitig gespeicherten Auftrag zu. Im nativen Ablauf können eigenständige API Checkout-Ereignisse checkoutSessionId und merchantOrderId enthalten, ohne dass paylinkId vorhanden ist. Lehnen Sie einen gültigen eigenständigen Kauf nicht allein wegen einer fehlenden Paylink-ID ab. Ebenso identifiziert eine wiederverwendbare Paylink-ID für sich genommen den Auftrag eines Käufers nicht eindeutig.

Prüfen Sie vor der Freigabe die erwartete Organisation, Umgebung, den Zahlungsversuch und den Kontext des geschäftlich vereinbarten Betrags. Das dokumentierte Feld amount bezeichnet den endgültigen Händlererlös im Zahlungstoken; es entspricht nicht automatisch Ihrem ursprünglichen Rechnungsbetrag in Landeswährung. Vergleichen Sie diese Zahlen nicht so, als hätten sie dieselbe Einheit. Bewahren Sie den ursprünglichen, serverseitig genehmigten Auftrag und seinen Preiskontext auf.

Verwenden Sie für dynamische Käufe den API Checkout-Ablauf, um die Zuordnung zwischen Auftrag und Sitzung zu erhalten. Für feste Produkte bieten Zahlungslinks einen wiederverwendbaren Zahlungseinstieg; die Entscheidung über die Erfüllung bleibt bei Ihrer Anwendung.

Sichern Sie die Wirkung ab, nicht nur die Ereignistabelle

Wird ein Auftrag vollständig innerhalb Ihrer Datenbank erfüllt, speichern Sie das Ereignisergebnis und den Zustandswechsel des Auftrags in einer einzigen Transaktion. Erzwingen Sie eine eindeutige Geschäftsaktion, etwa eine einzige Berechtigungsvergabe pro Einmalauftrag. Ein doppeltes Ereignis sollte das vorhandene Ergebnis zurückgeben und keine weitere Berechtigung erteilen.

Ruft die Auftragserfüllung einen anderen Dienst auf, verwenden Sie einen dauerhaften Ausgangsspeicher: Speichern Sie die geplante Aktion zusammen mit dem Zustandswechsel des Auftrags und lassen Sie sie anschließend von einem Verarbeitungsprozess zustellen. Geben Sie der Aktion beim nachgelagerten Dienst einen stabilen, auf dem Auftrag beruhenden Idempotenzschlüssel, sofern der Empfänger dies unterstützt. Der Ausgangsspeicher allein verhindert kein entferntes Duplikat, wenn der Verarbeitungsprozess nach erfolgreicher Ausführung der entfernten Aktion abstürzt.

Unterstützt ein Ziel weder Idempotenz noch eine Ergebnisabfrage, lassen Sie einen ungewissen Ausgang zur Abstimmung offen, statt eine unumkehrbare Aktion blind zu wiederholen. „Genau einmal“ kann ein HTTP-Webhook nicht über beliebige Datenbanken, Warteschlangen und externe Dienste hinweg garantieren.

Verhindern Sie, dass veraltete Ereignisse einen abgeschlossenen Auftrag zurücksetzen. Ein Ereignis invoice.overdue betrifft einen einzelnen Versuch und darf einen erfüllten Auftrag nicht aufheben. Bei wiederkehrendem Zugang unterscheidet der Anbieter Rechnungsereignisse von subscription.overdue und subscription.cancelled; setzen Sie die dokumentierten Abonnementregeln separat um.

Testen Sie Fehlerfälle, bevor Sie echte Aufträge annehmen

Verwenden Sie diese Abnahmefälle für Ihren Empfänger und Verarbeitungsprozess:

• Stellen Sie dasselbe signierte Ereignis zweimal und gleichzeitig zu: ein gespeichertes Ereignis, eine geschäftliche Wirkung.
• Unterbrechen Sie den Verarbeitungsprozess vor und nach dem Zustandswechsel des Auftrags: Die Wiederherstellung darf den Zugang nicht zweimal freischalten.
• Stellen Sie zwei bestätigte Zahlungsversuche für einen Auftrag zu: einmal erfüllen und den zusätzlichen Zahlungseingang kennzeichnen.
• Senden Sie eine ungültige Signatur, eine abweichende Organisation und einen unbekannten Auftrag: keine Auftragserfüllung.
• Stellen Sie nach der Bestätigung ein älteres Rechnungsereignis zu: keine Rücknahme der abgeschlossenen Auftragserfüllung.
• Senden Sie ein Ereignis im Testmodus an den Produktionsempfänger: keine echte Lizenz, Lieferung oder Kontogutschrift.

Testereignisse aus Yolfis Verwaltungsoberfläche verwenden livemode: false und eine evt_test_-ID. Sie prüfen die Zustellung und Nutzdatenverarbeitung, erzeugen jedoch keine echten Zahlungsdatensätze. Trennen Sie Testwirkungen und echte Wirkungen ausdrücklich; eine erfolgreiche Testbenachrichtigung ist kein Nachweis für einen abgewickelten Kauf.

Überwachen Sie authentifizierte Ereignisse, die auf Verarbeitung warten, Fehler der Verarbeitungsprozesse und bestätigte Zahlungen ohne Erfüllungsergebnis. Verknüpfen Sie diese Ausnahmefälle mit der Checkliste zum Zahlungsabgleich. Ist der zweite Zahlungseingang eine echte zusätzliche Zahlung und kein Wiederholungsversuch, folgen Sie dem Prüfverfahren für Rückerstattungen, statt die Belege zu löschen.

Häufig gestellte Fragen

Verhindert die Signaturprüfung doppelte Gutschriften?

Nein. Sie prüft Authentizität und Integrität. Ein echtes Ereignis kann mehrfach eintreffen, und eine zuvor gültige Anfrage kann erneut eingespielt werden. Speichern Sie Ereignis-IDs dauerhaft und erzwingen Sie eine geschäftliche Eindeutigkeitsbedingung auf Auftragsebene.

Sollte ich Erfolg zurückmelden, bevor ich das Ereignis speichere?

Nein. Bestätigen Sie erst nach der dauerhaften Annahme und führen Sie langsamere Arbeiten anschließend asynchron aus. Andernfalls kann ein Absturz nach der Antwort dazu führen, dass das Ereignis unbemerkt verloren geht.

Reicht ein Transaktionshash als Schlüssel zur Duplikaterkennung aus?

Nicht für die Webhook-Verarbeitung. Verwenden Sie für Ereigniszustellungen die dokumentierte signierte Ereignis-ID und für die Auftragserfüllung Ihren eigenen Auftragsschlüssel. Übertragungen und Aufträge haben unterschiedliche Identitäten; eine Transaktion kann mehrere Übertragungen enthalten.

Kann ich denselben Verarbeiter für Nutzdaten von Adaptern verwenden?

Nicht ohne die jeweilige Schnittstellenvereinbarung zu prüfen. Dieser Artikel beschreibt das native Format mit dem Adapter NONE. Anbieterkompatible Adapter können anders strukturierte Nutzdaten haben; validieren Sie ihre dokumentierten Felder, bevor Sie native Regeln zum Einlesen und Zuordnen wiederverwenden.

Fazit: bestätigen, speichern und einmal erfüllen

Zuverlässige Automatisierung von Kryptozahlungen trennt die authentifizierte Ereigniszustellung von der geschäftlichen Wirkung auf den Auftrag. Prüfen Sie die Signatur der unveränderten Anfrage, speichern Sie das Ereignis dauerhaft, ordnen Sie den Auftrag zu und sichern Sie die Erfüllung gegen Wiederholungen ab. Beginnen Sie für feste Produkte mit Yolfi-Zahlungslinks oder für dynamische Aufträge mit der dokumentierten serverseitig erstellten Sitzung. Die Anwendung bleibt dafür verantwortlich, jeden Kauf nur einmal freizuschalten.