Eine klassische API funktioniert nach dem Bringschuld-Prinzip: Der Client fragt, der Server antwortet. Doch was tust du, wenn du wissen willst, sobald etwas passiert – eine Zahlung eingeht, ein Paket versandt wird, ein neuer Kommentar erscheint? Du könntest die API alle paar Sekunden abfragen. Das ist verschwenderisch und langsam. Die elegante Lösung heißt Webhook: Statt selbst zu fragen, lässt du dich benachrichtigen. Dieser Artikel erklärt, wie Webhooks funktionieren und wie du sie sicher und zuverlässig betreibst.
Was ein Webhook ist
Ein Webhook ist eine umgekehrte API. Bei einer normalen API rufst du einen fremden Server an. Bei einem Webhook ruft der fremde Server dich an, sobald ein bestimmtes Ereignis eintritt. Du hinterlegst beim Anbieter eine URL – deinen Endpunkt – und der Anbieter schickt an diese URL einen HTTP-POST-Request, sobald das Event passiert. Man nennt Webhooks deshalb auch HTTP-Callbacks oder „Reverse APIs".
Das Muster ist überall: Zahlungsanbieter melden erfolgreiche Transaktionen per Webhook, Versanddienstleister melden Statusänderungen, Code-Plattformen melden neue Commits, Chat-Dienste melden eingehende Nachrichten. Immer dasselbe Prinzip: ein Ereignis tritt ein, eine HTTP-Anfrage landet bei dir.
Webhook gegen Polling
Um den Wert von Webhooks zu verstehen, lohnt der Vergleich mit der Alternative, dem Polling: dem wiederholten Abfragen einer API in festen Intervallen.
- Polling ist einfach, aber ineffizient. Fragst du jede Minute, sind 99 % der Anfragen vergeblich, weil sich nichts geändert hat. Außerdem entsteht eine Verzögerung von bis zu einer Minute.
- Webhooks liefern Ereignisse nahezu in Echtzeit und erzeugen nur dann Last, wenn wirklich etwas passiert. Der Preis: Du brauchst einen öffentlich erreichbaren Endpunkt und musst mit den Tücken eingehender Anfragen umgehen.
Für seltene oder besonders kritische Daten kann Polling als robuster Fallback dienen. In den meisten Echtzeit-Szenarien sind Webhooks aber die deutlich bessere Wahl.
Anatomie einer Webhook-Anfrage
Ein eingehender Webhook ist ein gewöhnlicher HTTP-POST mit einem JSON-Body. Typischerweise enthält die Payload:
- einen Event-Typ (z. B.
payment.succeededoderorder.shipped), - eine eindeutige Event-ID,
- einen Zeitstempel,
- die eigentlichen Nutzdaten zum Ereignis.
Im Header findest du häufig eine Signatur und manchmal die Event-ID separat. Dein Endpunkt sollte den Event-Typ auswerten und je nach Art unterschiedlich reagieren – ein einziger Endpunkt verarbeitet so viele verschiedene Ereignisse.
Sicherheit: Signaturen prüfen
Hier liegt die größte Gefahr. Dein Webhook-Endpunkt ist öffentlich erreichbar – also kann theoretisch jeder gefälschte Anfragen schicken. Stell dir vor, ein Angreifer schickt deinem Shop einen gefälschten payment.succeeded-Event und du schaltest eine Bestellung frei, ohne dass je Geld geflossen ist. Genau deshalb musst du jede eingehende Anfrage verifizieren.
Seriöse Anbieter unterschreiben jeden Webhook mit einem HMAC-Verfahren: Sie berechnen aus dem Body und einem geteilten Geheimnis (dem Webhook Secret) eine Signatur und legen sie in einen Header. Dein Endpunkt berechnet dieselbe Signatur mit demselben Geheimnis und vergleicht beide. Stimmen sie überein, ist die Anfrage echt und unverändert. So gehst du vor:
- Lies den rohen Request-Body ein, bevor du ihn parst – die Signatur bezieht sich auf die exakten Bytes.
- Berechne die HMAC-Signatur mit deinem Webhook Secret.
- Vergleiche sie mit dem Wert aus dem Header, und zwar mit einem zeitkonstanten Vergleich, um Timing-Angriffe zu verhindern.
- Lehne die Anfrage bei Abweichung mit Status 401 ab.
Zusätzlich solltest du den Zeitstempel prüfen und sehr alte Anfragen verwerfen – das erschwert Replay-Angriffe, bei denen eine abgefangene Anfrage später erneut gesendet wird. Das Webhook Secret gehört wie jedes andere Geheimnis in eine Umgebungsvariable, niemals in den Code. Mehr zu sicheren Geheimnissen und Tokens liest du in unserem Artikel zur API-Authentifizierung.
Schnell antworten, langsam verarbeiten
Eine zentrale Regel: Antworte sofort mit Status 200, bevor du mit der eigentlichen Verarbeitung beginnst. Die meisten Anbieter erwarten innerhalb weniger Sekunden eine Bestätigung. Dauert deine Verarbeitung zu lange – etwa weil du E-Mails versendest oder Rechnungen erstellst – läuft ein Timeout, der Anbieter wertet die Zustellung als gescheitert und schickt den Webhook erneut.
Die bewährte Lösung: Nimm den Webhook an, validiere die Signatur, lege das Event in eine Warteschlange (Queue) und antworte sofort mit 200. Die eigentliche Arbeit erledigt ein Hintergrundprozess. So entkoppelst du Annahme und Verarbeitung und bleibst immer schnell genug.
Retries und Idempotenz
Webhooks werden „mindestens einmal" zugestellt – das heißt, du kannst denselben Event mehrfach empfangen. Das passiert, wenn deine erste Antwort verzögert war oder dein Server kurz nicht erreichbar war und der Anbieter die Zustellung wiederholt. Wenn du nicht aufpasst, buchst du eine Zahlung doppelt oder versendest eine Bestätigungsmail mehrfach.
Die Lösung heißt Idempotenz: Dein Endpunkt muss so gebaut sein, dass die mehrfache Verarbeitung desselben Events keinen Schaden anrichtet. Praktisch speicherst du die Event-IDs bereits verarbeiteter Webhooks und ignorierst Wiederholungen. Trifft eine Event-ID ein, die du schon kennst, antwortest du einfach mit 200 und tust sonst nichts.
Gute Anbieter wiederholen fehlgeschlagene Zustellungen über Stunden oder Tage mit wachsenden Abständen (exponential backoff). Plane einen Endpunkt ein, der auch nach längerer Ausfallzeit alle nachgereichten Events korrekt verarbeitet.
Webhooks lokal testen
Ein Problem beim Entwickeln: Dein lokaler Rechner ist aus dem Internet nicht erreichbar, der Anbieter kann deinen Endpunkt also nicht aufrufen. Hier helfen Tunnel-Dienste, die deinen lokalen Server vorübergehend unter einer öffentlichen URL verfügbar machen. So kannst du echte Webhook-Anfragen direkt im Debugger nachvollziehen.
Alternativ schickst du dir Testanfragen selbst – etwa mit einem API-Client wie Postman oder Bruno. Achte dabei darauf, eine gültige Signatur mitzuschicken, sonst lehnt dein eigener Endpunkt die Testanfrage zu Recht ab. Viele Anbieter bieten zudem ein Dashboard, in dem du Test-Events auslösen und fehlgeschlagene Zustellungen erneut senden kannst.
Best Practices auf einen Blick
- Verifiziere jede Anfrage über die Signatur – ohne Ausnahme.
- Antworte schnell mit 200 und verarbeite asynchron in einer Queue.
- Mache deinen Handler idempotent über die Event-ID.
- Logge eingehende Webhooks für die Fehlersuche.
- Behandle unbekannte Event-Typen tolerant – Anbieter führen neue ein.
- Nutze HTTPS für deinen Endpunkt.
Wie Webhooks in das größere Bild sauberer Schnittstellen passen, zeigt unser Leitfaden zu REST-API-Design. Eine Sammlung praktischer Helfer für den Entwickleralltag findest du außerdem in unseren Webtools.
Häufige Fragen
Was ist der Unterschied zwischen Webhook und API?
Bei einer API stößt du die Kommunikation an (du fragst). Bei einem Webhook stößt der Anbieter sie an (er benachrichtigt dich). Ein Webhook ist also gewissermaßen eine API in umgekehrter Richtung – dein Server stellt den Endpunkt bereit, den der andere aufruft.
Wie verhindere ich gefälschte Webhooks?
Indem du jede Anfrage anhand der mitgelieferten Signatur und deines Webhook Secrets per HMAC verifizierst und ungültige Anfragen ablehnst. Ohne Signaturprüfung könnte jeder beliebige Daten an deinen öffentlichen Endpunkt senden.
Was passiert, wenn mein Server gerade offline ist?
Seriöse Anbieter wiederholen die Zustellung über einen längeren Zeitraum mit wachsenden Abständen. Sobald dein Server wieder erreichbar ist, kommen die nachgereichten Events an – vorausgesetzt, dein Handler verarbeitet sie idempotent.
Sollte ich Webhooks oder Polling verwenden?
Für echtzeitnahe Ereignisse sind Webhooks effizienter und schneller. Polling bleibt sinnvoll als Fallback oder wenn du keinen öffentlichen Endpunkt bereitstellen kannst. Viele robuste Systeme kombinieren beides: Webhooks für die Geschwindigkeit, gelegentliches Polling als Sicherheitsnetz.