Ein Webhook ist eine HTTP-Anfrage, die ein Dienst automatisch an eine vorher hinterlegte URL schickt, sobald ein bestimmtes Ereignis eintritt, etwa eine neue Bestellung oder eine Anmeldung zum Newsletter. Der Empfänger muss nicht nachfragen, er wird benachrichtigt.
Ein Webhook meldet ein Ereignis per HTTP-Anfrage an eine hinterlegte URL, Push statt Abfrage: wie er funktioniert, wie man ihn absichert, wofür er dient.
Was ein Webhook bedeutet
Jeff Lindsay beschrieb Webhooks im Mai 2007 als benutzerdefinierte Rückrufe über HTTP POST. Der Nutzer gibt eine URL an, und die Anwendung schickt dorthin eine Nachricht, wenn etwas passiert. Die Spezifikation Standard Webhooks nennt Webhooks heute die gängige Bezeichnung für HTTP-Callbacks, über die sich Dienste gegenseitig über Ereignisse informieren.
Der Unterschied zur gewöhnlichen API liegt in der Richtung. Bei einer API fragt das eigene Programm nach, ob es etwas Neues gibt: Das ist Pull. Bei einem Webhook meldet sich der andere Dienst von selbst, sobald es etwas Neues gibt: Das ist Push. Wer alle fünf Minuten nachfragt, schickt viele Anfragen ohne Ergebnis und erfährt ein Ereignis im schlimmsten Fall fünf Minuten zu spät.
Webhooks ergänzen APIs, sie ersetzen sie nicht. Oft enthält der Webhook nur die Nachricht, dass sich etwas geändert hat, und die Einzelheiten holt der Empfänger danach über die API.
Wie es funktioniert
Der Ablauf hat drei Schritte. Zuerst richtet der Empfänger eine Adresse ein, den Endpoint, die Anfragen annehmen kann, und trägt sie beim sendenden Dienst ein, zusammen mit den Ereignissen, die ihn interessieren. Tritt eines davon ein, schickt der Dienst eine HTTP-POST-Anfrage an diese Adresse, meist mit den Daten im Format JSON. Der Empfänger bestätigt den Eingang mit einem Statuscode der 2xx-Reihe.
Ein Beispiel aus dem E-Mail-Marketing: Mailchimp kann über Webhooks melden, wenn sich jemand an- oder abmeldet, seine E-Mail-Adresse ändert oder eine Kampagne verschickt wurde. Ein CRM kann so den Status eines Kontakts sofort anpassen, ohne die Liste regelmäßig abzugleichen.
Zwei Dinge regelt jeder Anbieter selbst. Das erste ist die Wartezeit. GitHub erwartet eine Antwort mit Status 2xx innerhalb von zehn Sekunden, sonst bricht es die Verbindung ab und wertet die Zustellung als fehlgeschlagen. Das zweite sind Wiederholungen. GitHub stellt fehlgeschlagene Zustellungen nicht automatisch erneut zu. Stripe dagegen versucht es im Live-Modus bis zu drei Tage lang mit exponentiell wachsenden Abständen. Ein Empfänger muss deshalb in der Doku des jeweiligen Dienstes nachlesen, was bei einem Ausfall verloren geht.
EmpfängerSendender Dienst
1Der Empfänger richtet eine Adresse ein, den Endpoint, die Anfragen annehmen kann, und trägt sie beim sendenden Dienst ein, zusammen mit den Ereignissen, die ihn interessieren.
Endpoint und Ereignisse
2Tritt eines davon ein, schickt der Dienst eine HTTP-POST-Anfrage an diese Adresse, meist mit den Daten im Format JSON.
HTTP-POST mit JSON
3Der Empfänger bestätigt den Eingang mit einem Statuscode der 2xx-Reihe.
Statuscode 2xx
Zwei Dinge regelt jeder Anbieter selbst: die Wartezeit und die Wiederholungen.
GitHubErwartet eine Antwort mit Status 2xx innerhalb von zehn Sekunden, sonst bricht es die Verbindung ab und wertet die Zustellung als fehlgeschlagen.Stellt fehlgeschlagene Zustellungen nicht automatisch erneut zu.
✕
StripeVersucht es im Live-Modus bis zu drei Tage lang, mit exponentiell wachsenden Abständen.
bis zu drei Tage
Der Ablauf ist überall gleich, die Regeln für den Ausfall nicht.
Warum es zählt
Webhooks verbinden Werkzeuge, ohne dass jemand Daten von Hand überträgt. Eine neue Bestellung im Shop kann eine Rechnung, einen Eintrag im CRM und eine Folge-E-Mail auslösen. Viele Abläufe der Marketing Automation beruhen auf solchen Ereignissen.
Weil ein Endpoint öffentlich erreichbar ist, kann ihn jeder aufrufen. Deshalb signieren viele Anbieter ihre Webhooks. GitHub schickt im Header X-Hub-Signature-256 einen HMAC-Hash, der aus dem geheimen Schlüssel des Webhooks und dem Inhalt der Nachricht berechnet wird. HMAC ist ein Verfahren zur Nachrichtenauthentifizierung mit kryptografischen Hashfunktionen, beschrieben in RFC 2104 vom Februar 1997. Der Empfänger berechnet denselben Hash und vergleicht beide. GitHub und Stripe raten dazu, das mit einem Vergleich in konstanter Zeit zu tun statt mit einem einfachen Gleichheitsoperator.
Zwei weitere Eigenschaften muss ein Empfänger kennen. Stripe schreibt, dass ein Endpoint dasselbe Ereignis gelegentlich mehr als einmal erhalten kann, und dass Stripe die Reihenfolge der Ereignisse nicht garantiert. Stripe schreibt außerdem einen Zeitstempel in die Signatur; seine Bibliotheken lehnen standardmäßig Nachrichten ab, die älter als fünf Minuten sind, um wiederholt eingespielte Nachrichten abzuwehren.
Best Practices
Die Signatur jeder eingehenden Nachricht prüfen und Nachrichten ohne gültige Signatur verwerfen.
Den Hash in konstanter Zeit vergleichen, nicht mit einem einfachen Gleichheitsoperator.
Sofort mit 2xx antworten und die eigentliche Verarbeitung danach in einer Warteschlange erledigen.
Die ID jedes Ereignisses speichern und doppelt ankommende Ereignisse nur einmal verarbeiten.
Bei Ereignissen, deren Reihenfolge zählt, den aktuellen Stand über die API nachladen.
Nachlesen, ob der Dienst fehlgeschlagene Zustellungen wiederholt, und verlorene Ereignisse andernfalls selbst nachholen.
Häufige Fehler
Den Endpoint ohne Signaturprüfung betreiben, sodass jeder gefälschte Ereignisse einschleusen kann.
Lange Verarbeitung vor der Antwort erledigen und so die Zeitgrenze des Dienstes überschreiten.
Jedes Ereignis als einmalig behandeln und zum Beispiel eine Bestellung doppelt anlegen.
Davon ausgehen, dass jeder Dienst fehlgeschlagene Zustellungen automatisch wiederholt.
Den geheimen Schlüssel im Quelltext oder in einem öffentlichen Repository ablegen.
Manuel Riveiro RodriguezCEO & Digital Strategist
Eine technische Prüfung sieht sich das und alles Weitere in einem Durchgang an.
Ein Webhook ist eine HTTP-Anfrage, die ein Dienst automatisch an eine hinterlegte URL schickt, sobald ein bestimmtes Ereignis eintritt. So erfährt zum Beispiel ein CRM sofort von einer neuen Bestellung oder Anmeldung, ohne regelmäßig nachfragen zu müssen. Die Daten kommen meist im Format JSON und per HTTP POST.
Was ist der Unterschied zwischen einem Webhook und einer API?
Bei einer API fragt das eigene Programm aktiv nach, ob es neue Daten gibt; das nennt man Pull. Bei einem Webhook meldet sich der andere Dienst von selbst, sobald etwas passiert; das nennt man Push. Beides wird oft kombiniert: Der Webhook meldet die Änderung, die Einzelheiten holt man über die API.
Wie sichert man einen Webhook ab?
Vor allem mit einer Signatur. Der Absender berechnet aus einem geheimen Schlüssel und dem Inhalt der Nachricht einen HMAC-Hash und schickt ihn im Header mit. Der Empfänger berechnet denselben Hash, vergleicht beide in konstanter Zeit und verwirft Nachrichten ohne gültige Signatur. Ein Zeitstempel schützt zusätzlich vor wiederholt eingespielten Nachrichten.
Was passiert, wenn der Empfänger nicht erreichbar ist?
Das hängt vom Dienst ab. Stripe wiederholt die Zustellung im Live-Modus bis zu drei Tage lang mit wachsenden Abständen. GitHub stellt fehlgeschlagene Zustellungen dagegen nicht automatisch erneut zu; sie lassen sich von Hand oder per Code nachholen. Deshalb gehört zu jedem Webhook ein Blick in die Doku des jeweiligen Anbieters.
Kann ein Webhook dasselbe Ereignis zweimal schicken?
Ja. Stripe schreibt ausdrücklich, dass ein Endpoint dasselbe Ereignis gelegentlich mehr als einmal erhalten kann, und dass die Reihenfolge der Ereignisse nicht garantiert ist. Ein Empfänger speichert deshalb die ID jedes verarbeiteten Ereignisses und überspringt Wiederholungen, damit etwa eine Bestellung nicht doppelt angelegt wird.
