Was ist ein Webhook? Definition, Sicherheit und Retries

Was ist ein Webhook?

Ein Webhook ist eine HTTP-Anfrage, fast immer ein POST, die ein Dienst an eine von Ihnen hinterlegte URL schickt, sobald auf seiner Seite etwas passiert. Sie geben dem Anbieter Ihre URL einmal an. Danach ruft er Sie bei jedem Ereignis mit einem kleinen JSON-Payload auf, zum Beispiel wenn eine Zahlung eingeht oder ein Build fertig ist. Nachfragen müssen Sie nie.

Webhooks vs. Polling

Ohne Webhooks fragen Sie per Polling ab: Ihr Code ruft die API des Anbieters im Takt auf und sucht nach Änderungen. Das hat drei Nachteile.

• Verzögerung. Bei 60 Sekunden Intervall wartet ein Ereignis im Schnitt 30 Sekunden, bis Sie es bemerken.
• Verschwendung. Die meisten Abfragen liefern nichts Neues, verbrauchen aber Bandbreite und zählen gegen die Rate Limits des Anbieters (siehe warum APIs Rate Limits setzen, englisch).
• Zielkonflikt. Schneller abfragen heißt Limits reißen, langsamer abfragen heißt später reagieren.

Ein Webhook dreht das um: Die Seite, die das Ereignis kennt, meldet es sofort.

So läuft eine Webhook-Zustellung ab

1. Sie hinterlegen beim Anbieter eine HTTPS-URL, meist in einer Einstellungsseite.
2. Ein Ereignis tritt ein: Ein Kunde zahlt, ein Pull Request wird gemergt, ein Monitor schlägt fehl.
3. Der Anbieter baut einen Payload, etwa {"event": "charge.succeeded", "data": {"id": "ch_123", "amount": 1500}}, und schickt ihn per POST an Ihre URL, mit Headern wie Ereignistyp, Delivery-ID und Signatur.
4. Ihr Endpunkt prüft die Anfrage, speichert oder queued das Ereignis und antwortet mit einem 2xx-Status.
5. Antwortet er mit einem Fehler oder gar nicht, versucht der Anbieter es später erneut.

Jeden Webhook verifizieren

Jeder, der Ihre URL kennt, kann dorthin POSTen. Ein ungeprüfter Handler lässt sich so dazu bringen, Bestellungen als bezahlt zu markieren oder Zugriff zu gewähren. Die übliche Abwehr ist eine HMAC-Signatur: Der Anbieter signiert den exakten Request-Body mit einem gemeinsamen Secret (HMAC ist in RFC 2104 definiert) und sendet das Ergebnis in einem Header. Sie berechnen es neu und lehnen Abweichungen ab. Stripe nutzt den Header Stripe-Signature, und seine Bibliotheken weisen Zeitstempel, die älter als 5 Minuten sind, standardmäßig ab. Das verhindert Replays.

Zwei Details verursachen die meisten Fehler. Erstens braucht die Signaturprüfung den rohen Body, parsen Sie das JSON also nicht und serialisieren es neu, bevor Sie prüfen. Zweitens sollten Signaturen in konstanter Zeit verglichen werden. Ein statisches Bearer Token im Header ist schwächer, weil sich eine einzige abgefangene Anfrage wiederholen lässt. Eine IP-Allowlist hilft als zusätzliche Schicht, bricht aber, wenn Anbieter Adressen ändern.

Wiederholungen, Duplikate und Reihenfolge

Die Zustellung erfolgt mindestens einmal, nicht genau einmal. Stripe wiederholt ein fehlgeschlagenes Ereignis im Live-Modus bis zu drei Tage lang, und GitHub erwartet eine 2xx-Antwort innerhalb von 10 Sekunden. Ihr Handler sieht also Duplikate und manchmal Ereignisse in falscher Reihenfolge (Stripe garantiert keine Reihenfolge).

• Handler idempotent machen. Speichern Sie die Ereignis- oder Delivery-ID und überspringen Sie bekannte IDs.
• Schnell bestätigen, später arbeiten. Ereignis speichern, 200 zurückgeben, aus einer Queue verarbeiten.
• Sich nicht auf die Reihenfolge verlassen. Kommt order.fulfilled vor order.created, holen Sie das aktuelle Objekt per API, statt der Abfolge zu trauen.

Häufige Webhook-Fehler

• Signaturprüfung weglassen, weil "die URL ja niemand kennt".
• Den Body vor der Prüfung parsen, sodass die Signatur nie passt.
• Langsame Arbeit im Request erledigen, was Timeouts und dann doppelte Wiederholungen auslöst.
• 200 zurückgeben, obwohl das Speichern fehlschlug, sodass der Anbieter nie wiederholt.
• Nur auf localhost testen. Nutzen Sie einen Tunnel oder die CLI des Anbieters, um echte Ereignisse weiterzuleiten, und spielen Sie ein Ereignis mit curl nach, um den Handler zu prüfen.
• Nie ins Zustellprotokoll des Anbieters schauen, sodass Fehler unbemerkt bleiben.

Webhooks im Monitoring

Über Webhooks übergeben Monitore einen Alarm an Ihre eigenen Werkzeuge. Im LoadFocus API-Monitoring sendet ein Webhook-Alert-Kanal einen HTTP-POST mit JSON-Body an eine HTTPS-URL unter Ihrer Kontrolle, wenn ein Check fehlschlägt, sich erholt, nur eingeschränkt läuft oder ein SSL-Zertifikat bald abläuft. Der Payload enthält Felder wie event (zum Beispiel check.failed), Name und URL des Checks, Status, Standort und Zeitstempel. Ihr Endpunkt sollte schnell mit 2xx antworten. Beim Speichern des Kanals wird einmalig ein Bestätigungs-POST gesendet, die Einrichtung steht in der Dokumentation zum Webhook-Alert-Kanal (englisch). Halten Sie die Empfänger-URL schwer erratbar und prüfen Sie die Payload-Felder, bevor Sie darauf reagieren. Mehr zum Thema: API-Monitoring.

Häufige Fragen: Webhooks

Ist ein Webhook dasselbe wie eine Callback-URL?

Ja. Webhook, HTTP-Callback und Reverse API beschreiben dasselbe Muster: Ein Dienst ruft eine URL auf, die Sie ihm genannt haben, sobald ein Ereignis eintritt.

Was ist der Unterschied zwischen Webhooks und WebSockets?

Ein Webhook ist eine einmalige HTTP-Anfrage, die ein Anbieter bei einem Ereignis sendet. Ein WebSocket ist eine dauerhafte Zwei-Wege-Verbindung zwischen Client und Server. Webhooks passen zu gelegentlichen Ereignissen zwischen Diensten, WebSockets zu ständigem Zwei-Wege-Verkehr wie Chat.

Was passiert, wenn mein Endpunkt ausfällt?

Die meisten Anbieter wiederholen eine Weile und geben dann auf. Stripe wiederholt im Live-Modus zum Beispiel bis zu drei Tage lang. Danach müssen Sie Ereignisse selbst nachholen. Beobachten Sie also das Zustellprotokoll des Anbieters und halten Sie einen Weg bereit, verpasste Ereignisse neu abzurufen.

Wie teste ich einen Webhook-Handler lokal?

Anbieter erreichen localhost nicht. Machen Sie ihn über einen Tunnel wie ngrok erreichbar oder nutzen Sie die CLI des Anbieters zum Weiterleiten, wie die Stripe CLI. Danach spielen Sie gespeicherte Payloads mit curl nach, während Sie debuggen.

Webhooks oder Polling?

Webhooks, wenn Latenz zählt oder Ereignisse selten sind. Polling für Massen-Synchronisierung oder wenn Sie keinen öffentlichen HTTPS-Endpunkt betreiben können. Viele Integrationen kombinieren beides: Webhooks für Tempo, gelegentliches Polling, um Verpasstes aufzufangen.