Webhook-Zustellgarantien einfach erklärt

Zustellgarantien bei Webhooks beschreiben, wie oft und in welcher Reihenfolge ein Anbieter Ereignisse an Ihren Endpunkt liefert. Die meisten Anbieter versprechen bestenfalls eine Zustellung mindestens einmal (At-least-once). Ihr Endpunkt erhält die meisten Ereignisse, manchmal doppelt, manchmal verspätet und manchmal in falscher Reihenfolge. Zuverlässige Integrationen legen die Absicherungen auf die empfangende Seite.

Dieser Leitfaden erklärt jede Garantie in einfachen Worten, zeigt, was die Dokumentation realer Anbieter verspricht, und endet mit einer Checkliste für jede Webhook-Integration, auch für Krypto-Zahlungsereignisse.

TL;DR

• At-least-once ist die realistische Obergrenze. Anbieter wiederholen die Zustellung, bis Sie eine 2xx-Antwort zurückgeben, daher sind Duplikate normal und Sie müssen sie behandeln.
• Die Reihenfolge ist nicht garantiert. Ein früheres Ereignis mit Timeout kann nach einem späteren ankommen, daher sortieren Sie nach dem eigenen Zeitstempel oder Sequenzfeld des Ereignisses.
• Zuerst bestätigen, dann verarbeiten. Prüfen Sie die Signatur, speichern Sie das Ereignis dauerhaft, geben Sie 2xx zurück und erledigen Sie die aufwendige Arbeit danach asynchron.
• Deduplizieren Sie anhand der Ereignis-ID. Speichern Sie sie mit einem eindeutigen Index, bevor ein Nebeneffekt eintritt, etwa die Gutschrift eines Guthabens.
• Behandeln Sie Webhooks als Benachrichtigungen, nicht als Hauptbuch. Gleichen Sie kritische Datensätze planmäßig mit der API ab, um zu erfassen, was Wiederholungen verpasst haben.
• Chaingateway wiederholt fehlgeschlagene Benachrichtigungen nicht automatisch. Sie werden aufgelistet und auf Anfrage erneut gesendet.

Was bedeuten die drei Zustellgarantien?

Die Zustellsemantik stammt aus verteilten Systemen und lässt sich sauber auf Webhooks übertragen.

Garantie	Was der Absender tut	Was schiefgehen kann	Was Sie bauen
Höchstens einmal (At-most-once)	Sendet das Ereignis einmal und wiederholt nie	Das Ereignis geht verloren, wenn Ihr Endpunkt nicht erreichbar ist	Abgleich mit der API
Mindestens einmal (At-least-once)	Wiederholt, bis Sie bestätigen oder die Wiederholungen aufgebraucht sind	Duplikate, verspätete Ankunft, Neuordnung	Idempotenter Handler, Deduplizierung
Exakt einmal (Exactly-once)	Würde einmal zustellen, ohne Verlust und ohne Duplikate	Über eine unzuverlässige Netzwerkgrenze nicht erreichbar	At-least-once plus Deduplizierung

Bei At-most-once bedeutet ein fehlgeschlagener Versuch ein verlorenes Ereignis. Für den Absender ist das einfach, für alles, was Geld betrifft, ist es unsicher.

Bei At-least-once versucht der Absender weiter, bis er eine Erfolgsantwort sieht oder sein Wiederholungsbudget aufgebraucht ist. Verluste werden selten, aber es gibt einen Haken. Angenommen, Ihr Handler schreibt ein Konto gut und stürzt dann ab, bevor er 200 zurückgibt. Der Absender hat die Bestätigung nie gesehen und sendet das Ereignis daher erneut. Aus Sicht des Absenders ist das korrektes Verhalten. Aus Ihrer Sicht ist es eine doppelte Gutschrift, sofern Sie das nicht verhindern.

Exactly-once wünschen sich alle, und über HTTP kann es niemand versprechen. Der Absender kann nicht wissen, ob Ihr Server die Anfrage verarbeitet hat, wenn die Verbindung abbricht. Der praktische Ersatz ist At-least-once-Zustellung in Kombination mit einem Empfänger, der Wiederholungen ignoriert. Diese Kombination liefert Ihnen Exactly-once-Effekte, und auf die kommt es tatsächlich an.

Was versprechen Anbieter tatsächlich?

Lesen Sie den Abschnitt zur Zustellung in der Dokumentation eines seriösen Webhook-Anbieters, dann taucht immer dasselbe Muster auf.

Adobe I/O Events gibt an, dass jedes Ereignis pro Registrierung mindestens einmal zugestellt wird, Duplikate gesendet werden können und die Reihenfolge der Ereignisse nicht garantiert ist. Column, eine US-Banking-API, stellt fest, dass Webhook-Ereignisse nicht garantiert in der Reihenfolge ihrer Erstellung ankommen. Ein früheres Ereignis mit Timeout kann nach einem späteren eintreffen, weil jeder Wiederholungsversuch unabhängig neu geplant wird.

Dieses letzte Detail erklärt die meisten Reihenfolge-Fehler. Ereignis A schlägt einmal fehl und wird für einen Wiederholungsversuch in einer Minute eingeplant. Ereignis B, danach erstellt, gelingt sofort. Ihr System sieht B, dann A. Auf Seiten des Anbieters ist nichts kaputt. Die Garantie hat die Reihenfolge schlicht nie abgedeckt.

Reihenfolge: Die Uhr des Ereignisses nutzen, nicht die der Zustellung

Die Webhook-Richtlinien von Wise empfehlen, die Chronologie aus den Zeitstempeln der Ereignisse oder, wo verfügbar, aus monoton steigenden Sequenz-IDs zu rekonstruieren, statt aus dem Zeitpunkt des Versands. Die Dokumentation weist darauf hin, dass der Sendezeitpunkt vom Zeitpunkt des Ereignisses abweichen kann, besonders bei Wiederholungsversuchen.

In der Praxis:

1. Speichern Sie den geschäftlichen Zeitstempel oder die Sequenznummer des Ereignisses zusammen mit der Payload.
2. Wenn ein Ereignis eintrifft, vergleichen Sie es mit dem neuesten Stand, den Sie für dieses Objekt haben.
3. Ist das eingehende Ereignis älter als das, was Sie bereits angewendet haben, speichern Sie es, lassen es aber keinen neueren Stand überschreiben.

Bei einem Zahlungsstatus, der von „ausstehend“ zu „bestätigt“ wechselt, verhindert das, dass ein spätes Ereignis „ausstehend“ eine bestätigte Zahlung zurücksetzt.

Wie funktionieren Wiederholungen, und wann hören sie auf?

Wiederholungsrichtlinien unterscheiden sich, doch das Muster ist gleich: exponentielles Backoff, eine Obergrenze und ein harter Stopp. Chaingateway ist die Ausnahme, weil es nicht automatisch wiederholt.

Anbieter	Wiederholungsverhalten (laut Dokumentation)
Column	Bis zu 25 Wiederholungen innerhalb von drei Tagen, exponentielles Backoff, erster Wiederholungsversuch eine Minute nach der fehlgeschlagenen Zustellung
Probo	Bis zu 12 Versuche, exponentielles Backoff mit vollem Jitter ab einer Basis von 30 Sekunden, begrenzt auf vier Stunden
Stripe	Exponentielles Backoff im Live-Modus für bis zu drei Tage
Chaingateway	Keine automatische Wiederholung. Fehlgeschlagene Benachrichtigungen sind unter GET /api/v2/{chain}/webhooks/notifications/failed aufgelistet und werden mit POST /api/v2/{chain}/webhooks/notifications/{id}/retry erneut gesendet

Quellen: Column, Probo und Stripe Dokumentation, abgerufen am 5. November 2026, sowie die OpenAPI-Spezifikation von Chaingateway.

Die Dokumentation von Probo nennt weitere nützliche Details. Wiederholt werden Netzwerkfehler, Timeouts sowie Antworten mit 408, 425, 429 oder 5xx, und ein Retry-After-Header wird bis zur Obergrenze beachtet. Sind die Versuche ausgeschöpft, gilt die Zustellung als fehlgeschlagen und wird nicht erneut eingereiht.

Daraus folgen zwei Lehren. Erstens sind die Fehlercodes Ihres Endpunkts Signale: Ein 5xx fordert den Absender auf, es erneut zu versuchen. Geben Sie also nur dann einen 5xx-Code zurück, wenn Sie tatsächlich einen erneuten Versuch wollen. Zweitens ist das Wiederholungsfenster endlich. Ist Ihr Dienst länger ausgefallen als dieses Fenster, fehlen diese Ereignisse in der Wiederholungswarteschlange, und Sie brauchen einen anderen Weg, sie wiederherzustellen.

Warum sollte ich schnell bestätigen und später verarbeiten?

Eine Zustellung gilt als erfolgreich, wenn Sie einen 2xx-Status zurückgeben. Column betrachtet ein Ereignis als zugestellt, wenn es innerhalb von 10 Sekunden einen 2xx-Code erhält und empfiehlt, ihn direkt nach dem Empfang zurückzugeben, bevor eine umfangreiche Verarbeitung stattfindet. Die Dokumentation von NestJS behandelt 2xx als Erfolg und alles andere, einschließlich Weiterleitungen, Timeouts und abgelehnter Verbindungen, als Fehler.

Die Aufgabe des Handlers ist daher eng gefasst:

1. Lesen Sie den rohen Body.
2. Prüfen Sie die Signatur.
3. Prüfen Sie Ereignistyp und ID.
4. Schreiben Sie das Ereignis in dauerhaften Speicher (eine Datenbankzeile oder eine Queue-Nachricht).
5. Geben Sie 200, 202 oder 204 zurück.

Alles Weitere, etwa das Aktualisieren von Guthaben, das Versenden von E-Mails oder der Aufruf anderer Dienste, läuft in einem Worker, der aus diesem Speicher liest. Erledigen Sie die langsame Arbeit direkt im Handler, wird eine langsame Datenbankabfrage zum Timeout, der Timeout zum Retry und der Retry zum Duplikat. Den Ansatz aus Ingest, Queue und Fan-out behandelt unser eigener Artikel zu Webhooks vs. WebSockets.

Wie mache ich Duplikate unschädlich?

Da At-least-once-Zustellung Wiederholungen bedeutet, muss Ihr Handler idempotent sein. Die Standardmethode ist einfach.

Probo empfiehlt, die Signatur zu prüfen, die erwartete Organisation und den Ereignistyp zu bestätigen und dann die Ereignis-ID atomar mit einem eindeutigen Index zu speichern, bevor Nebeneffekte eintreten. Eine spätere Anfrage mit einer bereits gespeicherten ID wird ignoriert. Stripe gibt denselben Rat: verarbeitete Ereignis-IDs zu speichern und jedes bereits behandelte Ereignis zu überspringen. Viele Anbieter machen das leichter, indem sie in jeder Payload eine eindeutige ID mitliefern. Adobe etwa legt eine UUID in der Payload ab und wiederholt sie im Header x-adobe-event-id.

Ein minimales Muster:

1. Fügen Sie die Ereignis-ID in eine Tabelle mit einer Unique-Constraint ein.
2. Schlägt das Einfügen fehl, weil die ID bereits existiert, geben Sie 200 zurück und brechen ab.
3. Gelingt das Einfügen, stellen Sie die Arbeit in die Queue.

Die Reihenfolge ist entscheidend. Erst aufzeichnen, dann handeln. Handeln Sie zuerst und stürzen ab, bevor Sie aufzeichnen, wiederholt der Retry die Aktion. Zeichnen Sie zuerst auf und stürzen ab, bevor Sie handeln, sollte Ihr Worker beim Neustart unerledigte Datensätze aufnehmen, damit das Ereignis nicht stillschweigend verloren geht.

Bei Geldbewegungen fügen Sie eine zweite Schicht hinzu: Machen Sie auch den Geschäftsvorgang idempotent. Verknüpfen Sie die Gutschrift einer Einzahlung mit Transaktions-Hash und Log-Index oder der Zahlungs-ID, damit selbst ein Fehler in der Ereignistabelle dieselbe Zahlung nicht zweimal gutschreibt.

Wie verifiziere ich jede Anfrage?

Ein Webhook-Endpunkt ist eine öffentliche URL, die Aktionen in Ihrem System auslöst. Jeder kann an sie senden, sofern Sie nicht prüfen, wer die Anfrage geschickt hat.

Stripe verlangt eine Verifizierung mit dem rohen Request-Body, dem Signatur-Header und Ihrem Endpunkt-Geheimnis. Probo rät, den unveränderten Body zu verwenden und die Signatur zu prüfen, bevor das JSON geparst wird. Anschließend folgt eine Prüfung der Aktualität des Zeitstempels. Das Parsen und erneute Serialisieren des Bodys vor der Verifizierung ist eine klassische Ursache dafür, dass Signaturen nie übereinstimmen.

Eine solide Verifizierung für Anbieter, die den Body signieren:

• Berechnen Sie den HMAC über die exakt empfangenen Bytes mit Ihrem Geheimnis.
• Vergleichen Sie ihn mit dem Header-Wert in einem konstantzeitigen Vergleich.
• Weisen Sie Anfragen zurück, deren Zeitstempel außerhalb eines kurzen Toleranzfensters liegt, um wiederholte Mitschnitte zu begrenzen.
• Erst dann parsen Sie das JSON und prüfen den Ereignistyp.

Chaingateway funktioniert anders. Es berechnet einen Base64-HMAC-SHA256 über die txid aus der Payload und sendet ihn im Header X-Signature. Die Dokumentation zur Signatur zeigt die Prüfung, und unser Beitrag zur Webhook-Sicherheitsfunktion erklärt die Einrichtung.

Wie stelle ich Ereignisse wieder her, die Wiederholungen verpasst haben?

Auch ein perfekter Empfänger verliert in manchen Szenarien Ereignisse: ein Ausfall, der länger dauert als das Wiederholungsfenster, eine falsch konfigurierte Firewall oder ein Deployment, das stundenlang 500 zurückgibt. Die Wiederherstellungsoptionen unterscheiden sich je nach Anbieter. Probo bietet kein manuelles Replay, stellt fehlgeschlagene Zustellungen nicht erneut in die Warteschlange und erwartet, dass Sie bei Fehlern alarmieren und mit seiner API abgleichen. Stripe weist darauf hin, dass Betreiber einen Rückstand manuell abarbeiten können, um die Wiederherstellung zu beschleunigen. Column gibt an, dass fehlende oder zusätzliche Ereignisse über seine Event-APIs abgerufen werden können, wenn Fehler einen Abgleich erfordern.

Das gemeinsame Designprinzip, das die Entwicklerdokumentation von ThriveDesk klar benennt, lautet: Behandeln Sie Webhooks als Benachrichtigungen und nicht als einziges Ereignisprotokoll. Speichern Sie Payloads dauerhaft, verarbeiten Sie sie asynchron und gleichen Sie kritische Datensätze regelmäßig mit der REST-API ab.

Ein Abgleichsjob kann klein sein:

1. Listen Sie planmäßig die relevanten Objekte (Zahlungen, Wallets, Bestellungen) aus der API des Anbieters für den letzten Zeitraum auf.
2. Vergleichen Sie deren Status mit Ihren eigenen Datensätzen.
3. Wenden Sie Abweichungen über denselben idempotenten Codepfad an, den auch Ihr Webhook-Handler nutzt.
4. Alarmieren Sie, wenn der Job oft Lücken findet, denn das deutet auf ein Problem mit dem Endpunkt hin.

Da ein späteres Ereignis oft den vollständigen aktuellen Zustand eines Objekts enthält, kann ein verpasstes Zwischenereignis ohnehin vom nächsten überschrieben werden. Der Abgleich deckt die Fälle ab, in denen kein nächstes Ereignis kommt.

Wie gelten diese Garantien für Krypto-Zahlungsereignisse?

On-Chain-Zahlungen erhöhen den Einsatz, denn ein verpasstes oder doppeltes Ereignis bedeutet eine verpasste oder doppelte Gutschrift. Einige Gewohnheiten helfen unabhängig vom Anbieter:

• Gutschriften an Chain-Kennungen binden. Verwenden Sie den Transaktions-Hash plus den Transfer-Index darin, nicht allein die Zustellungs-ID des Webhooks.
• Status als Fortschritt modellieren. Ausstehend, bestätigt und final sind Zustände mit fester Reihenfolge. Lassen Sie nie zu, dass ein älterer Status einen neueren überschreibt.
• Mit eigenen Daten abgleichen. Suchen Sie die empfangende Adresse oder Referenz in Ihrer Datenbank, bevor Sie gutschreiben. Ignorieren Sie Ereignisse für Adressen, die Ihnen nicht gehören.
• Guthaben abgleichen. Ein planmäßiger Vergleich Ihres Hauptbuchs mit den Wallet-Guthaben aus der API erfasst alles, was der Ereignisstrom verloren hat.

Unsere Anleitung zur automatischen Verarbeitung von Einzahlungen mit Webhooks setzt diese Schritte in einen Zahlungsablauf um. Der Polygon-Webhooks-Leitfaden zeigt die ereignisgesteuerte Alternative zum Polling auf einer bestimmten Chain.

Unsere Perspektive

Wir bauen Webhooks für Entwickler, die Geld bewegen, deshalb denken wir täglich über Zustellgarantien nach. Unsere Ansicht ist, dass kein seriöser Anbieter Exactly-once-Zustellung versprechen kann. Die richtige Antwort ist ein sauberer Vertrag: Ereignisse sind Benachrichtigungen, signierte Anfragen belegen ihre Herkunft, und die API ist immer die Quelle der Wahrheit.

Deshalb verbinden wir Echtzeit-Ereignisbenachrichtigungen mit einer einheitlichen REST-API über alle Chains. Webhooks sagen Ihnen, dass etwas passiert ist. Die API erlaubt Ihnen, es zu bestätigen, dekodierte Transaktionsdaten abzurufen und bei Bedarf abzugleichen. Unsere Webhooks sind HMAC-signiert, damit Ihr Empfänger sie prüfen kann. Die Payload enthält den dekodierten Absender, Empfänger, Token-Contract und Betrag, sodass Ihr Handler seine Zeit auf Geschäftslogik verwendet statt auf das Parsen roher Logs.

Wir finden außerdem, dass Teams dafür keine eigenen Nodes betreiben oder chain-spezifische Endpunkte jonglieren sollten. Eine Integration, ein Signaturverfahren und eine Art, den Status über Ethereum, Bitcoin, Tron, Solana, Polygon, BNB Chain und Arbitrum abzufragen, bedeutet weniger Stellen, an denen ein Zustellungs-Randfall stecken kann.

Bitblade

Auf signierten Multi-Chain-Webhooks aufbauen

Wenn Sie Krypto-Zahlungen in eine App einbauen, liefern Chaingateway Webhooks Blockchain-Ereignisbenachrichtigungen mit HMAC-Signaturen. Dahinter steht eine Blockchain API für Wallets, Transfers, dekodierte Transaktionen und Gaspreise. Pläne auf der Preisseite beginnen bei 49 € pro Monat für Plus. Pro kostet 99 €, Premium 249 € und Enterprise 499 € pro Monat. Bei jährlicher Abrechnung liegen die Preise ab 490 €.

Kombinieren Sie den Webhook-Strom mit dem oben beschriebenen Abgleichsmuster, dann erhalten Sie schnelle Benachrichtigungen mit einem Sicherheitsnetz.

Quellen

• Adobe I/O Events FAQ
• Column: Events and Webhooks
• Wise Platform: Event ordering
• Probo Docs: Webhook Delivery and Recovery
• Stripe Documentation: Webhooks
• NestJS: Webhooks
• ThriveDesk Developer Docs: Retries, failures, and replay

Empfohlen

• Webhooks vs WebSockets for Developers: Ingest, Queue, Fan Out Pattern
• The Use of Webhooks to Process Deposits Automatically
• New Feature to Enhance Webhook Security
• Polygon Webhooks: Get Real-Time On-Chain Events Without Polling