Webhooks einfach erklärt: Funktionsweise, Unterschiede zur API und Anwendungsfälle

Webhook ist ein Mechanismus, mit dem ein System ein anderes automatisch über ein eingetretenes Ereignis informiert. Statt ständig Anfragen an den Server zu senden, erhält die Anwendung die Daten genau in dem Moment, in dem sie verfügbar sind - beispielsweise nach einer erfolgreichen Zahlung, einer neuen Bestellung oder einer Statusänderung bei der Lieferung.

Webhooks sind besonders nützlich bei der Integration mehrerer Dienste. Sie reduzieren überflüssige Anfragen und ermöglichen eine schnellere Reaktion auf Änderungen. Dabei stehen Webhooks in engem Zusammenhang mit klassischen APIs, funktionieren jedoch nach einem anderen Prinzip.

Was ist ein Webhook und wofür werden Webhooks benötigt?

Webhook einfach erklärt

Am einfachsten lässt sich der Unterschied zwischen API und Webhook anhand von Benachrichtigungen veranschaulichen.

Bei einer klassischen API arbeitet die Anwendung aktiv: Sie fragt regelmäßig einen anderen Server, ob neue Daten verfügbar sind. Wenn sich nichts geändert hat, wiederholt sie die Anfrage nach einiger Zeit.

Ein Webhook funktioniert umgekehrt. Die Anwendung teilt dem Dienst eine spezielle Adresse - die Webhook-URL - mit, und der Dienst sendet aus eigener Initiative eine Anfrage dorthin, sobald das gewünschte Ereignis eintritt.

So muss beispielsweise ein Onlineshop nicht ständig das Zahlungssystem fragen, ob eine Bestellung bezahlt wurde. Das Zahlungssystem sendet selbst einen Webhook unmittelbar nach Zahlungsbestätigung.

Daher werden Webhooks oft als Benachrichtigungsmechanismus zwischen Programmen bezeichnet. Ein System fragt nicht ständig den Status des anderen ab, sondern wartet einfach auf die Nachricht zum gewünschten Ereignis.

Welche Aufgaben lösen Webhooks?

Webhooks werden überall dort eingesetzt, wo ein System schnell auf Änderungen in einem anderen Dienst reagieren muss. Typische Beispiele:

• Ein Zahlungssystem informiert den Shop über eine erfolgreiche Zahlung.
• Ein CRM erhält Informationen über eine neue Anfrage von einer Website.
• Ein Lieferdienst sendet den neuen Bestellstatus.
• Eine Git-Plattform startet einen Build nach Hochladen neuen Codes.
• Ein Messenger leitet eine neue Nachricht an einen Bot weiter.
• Ein Cloud-Dienst meldet den Abschluss der Dateiverarbeitung.

Das Besondere an diesen Szenarien: Die Aktion wird durch ein Ereignis ausgelöst. Das System prüft nicht regelmäßig den Status, sondern erhält nur dann ein Signal, wenn tatsächlich etwas passiert ist.

Solche Prinzipien werden nicht nur bei einzelnen Integrationen, sondern auch in größeren Softwaresystemen eingesetzt. Mehr dazu im Beitrag Warum Event-driven-Architektur Systeme schneller und reaktionsfähiger macht.

Dadurch eignen sich Webhooks besonders für die Automatisierung. Nach dem Empfang eines Ereignisses kann ein Programm selbst den Bestellstatus ändern, eine Benachrichtigung an den Nutzer senden, Daten in einer Datenbank speichern oder einen weiteren Prozess starten.

Wie funktioniert ein Webhook?

Ereignis, URL und HTTP-Anfrage

Damit ein Webhook funktioniert, erstellt das empfangende System zunächst eine spezielle URL - den sogenannten Endpoint. An diese Adresse schickt der externe Dienst die Benachrichtigungen über Ereignisse.

Das Prinzip ist einfach:

1. Ereignis tritt ein
2. Der Dienst formatiert die Daten
3. Versendet eine HTTP-Anfrage
4. Das empfangende System verarbeitet die Anfrage

Beispiel: Ein Nutzer bezahlt eine Bestellung. Das Zahlungssystem registriert die erfolgreiche Transaktion und sendet eine HTTP-Anfrage an die Webhook-URL des Onlineshops. Nach Empfang der Anfrage ändert der Shop den Bestellstatus auf "Bezahlt" und kann automatisch weitere Aktionen einleiten.

Für Webhooks wird meist die HTTP-Methode POST verwendet, da mit der Anfrage auch Ereignisdaten übermittelt werden. Das genaue Format hängt jedoch vom jeweiligen Dienst ab - manche Plattformen nutzen auch andere HTTP-Methoden.

Was enthält eine Webhook-Anfrage?

Eine Webhook-Anfrage besteht in der Regel aus mehreren Teilen: Die URL enthält die Adresse des Handlers, die HTTP-Header können technische Daten transportieren und die Hauptinformationen zum Ereignis stehen im Body der Anfrage.

Viele Dienste übertragen die Daten im JSON-Format. Eine Benachrichtigung über eine Zahlung könnte beispielsweise folgende Informationen enthalten: Bestell-ID, Betrag, Währung, Zahlungsstatus und Zeitpunkt der Transaktion.

{
  "event": "payment.success",
  "order_id": "A1024",
  "status": "paid"
}

Nach Erhalt liest die Anwendung das Feld event, ermittelt den Ereignistyp und startet die passende Logik. Bei einer Zahlung wird die Bestellung als "bezahlt" markiert, bei einer Lieferung wird der Status aktualisiert.

Nach erfolgreicher Verarbeitung gibt der Webhook-Server meist einen HTTP-Statuscode zurück. Ein Code im Bereich 200 signalisiert Erfolg. Bei Fehlern oder keiner Antwort kann der sendende Dienst die Übertragung erneut versuchen.

Beispiel für einen Webhook in der Praxis

Stellen wir uns einen Onlineshop mit angebundener externer Zahlungsplattform vor. Der Käufer bestellt und gelangt zur Zahlungsseite. Nach Abschluss des Zahlungsprozesses erhält das Zahlungssystem die Bestätigung der Bank - der Shop weiß zu diesem Zeitpunkt eventuell noch nichts vom Ergebnis.

Statt dass der Shop ständig den Zahlungsstatus per API abfragt, sendet das Zahlungssystem einen Webhook:

• payment.success → Webhook des Shops → Statusänderung der Bestellung

Der Server des Shops nimmt die Benachrichtigung entgegen, prüft die Daten und setzt den Bestellstatus automatisch auf "Bezahlt". Danach kann das System z.B. eine Quittung versenden, das Lager informieren und die Vorbereitung des Versands starten.

Dieser Ansatz ist besonders nützlich bei Prozessen, bei denen das Ereignis Sekunden, Minuten oder sogar Stunden nach der ursprünglichen Anfrage auftreten kann. Die Anwendung muss nicht ständig den Status abfragen, sondern wartet einfach auf den Webhook.

Webhook vs. API - Wo liegt der Unterschied?

API arbeitet auf Anfrage, Webhook auf Ereignis

Der Hauptunterschied zwischen Webhook und klassischem API besteht darin, wer den Datenaustausch initiiert.

Bei der Arbeit mit einer API sendet die Anwendung aktiv Anfragen an den Server - etwa um eine Bestellübersicht zu erhalten, ein Nutzerprofil abzurufen oder den Zahlungsstatus zu prüfen. Der Server antwortet erst nach einer solchen Anfrage.

Ein Webhook funktioniert anders: Der Empfänger teilt seine URL im Voraus mit, und der Quell-Dienst sendet eine Anfrage, sobald ein relevantes Ereignis eintritt.

Man kann es als zwei Modelle betrachten:

• API - "Fragen, ob etwas passiert ist"
• Webhook - "Eine Nachricht erhalten, wenn etwas passiert ist"

In der technischen Dokumentation werden diese Ansätze oft mit Pull- und Push-Modellen verknüpft. Die API wird für Pull verwendet (der Client holt die Daten aktiv ab), der Webhook für Push (die Daten werden dem Empfänger automatisch gesendet).

Webhook vs. REST API

Webhook und REST API nutzen dieselben grundlegenden Internettechnologien: HTTP, URL, Header, Methoden wie POST und Datenformate wie JSON. Ihr Zweck ist jedoch unterschiedlich.

So kann ein Shop per API Informationen zu einer bestimmten Zahlung abrufen. Über den Webhook informiert das Zahlungssystem den Shop proaktiv über eine erfolgreiche Zahlung.

Deshalb sind Webhook und API keine sich gegenseitig ausschließenden Technologien.

Webhook ersetzt die API nicht

In der Praxis werden Webhooks und APIs häufig gemeinsam eingesetzt.

Eine API wird gebraucht, wenn eine Anwendung selbst Daten abrufen oder ändern muss. Ein Webhook hingegen informiert schnell über eingetretene Ereignisse.

Beispiel: In einem CRM kann die Anwendung über die API Kundendaten abrufen oder ändern. Der Webhook benachrichtigt externe Systeme über neue Kunden oder geänderte Phasen bei Deals.

Oft enthält ein Webhook nur minimale Informationen, wie eine Objekt-ID und den Ereignistyp. Danach holt die Anwendung die vollständigen Daten per API.

So lässt sich die Anzahl ständiger Anfragen verringern und gleichzeitig die Flexibilität der API bewahren.

Wann Webhook nutzen und wann eine klassische API?

Wann ist Webhook sinnvoller?

Ein Webhook eignet sich besonders, wenn das System unmittelbar nach Eintritt eines Ereignisses benachrichtigt werden soll.

Typische Beispiele sind Zahlungsbestätigungen, neue Bestellungen, Statusänderungen bei Lieferungen, neue Leads im CRM, Datei-Uploads oder das Publishing neuen Codes in Repositories.

Regelmäßige API-Anfragen erzeugen in solchen Szenarien unnötige Last, da viele Anfragen oft das gleiche Ergebnis liefern. Mit einem Webhook wird eine Anfrage nur bei tatsächlicher Änderung versendet.

Deshalb sind Webhooks besonders praktisch für die Automatisierung und Integration von Services, die möglichst sofort auf Ereignisse reagieren müssen.

Wann ist eine API besser geeignet?

Die klassische API bleibt vorteilhaft, wenn Anwendungen Daten zu beliebigen Zeitpunkten abrufen müssen.

Beispielsweise möchte ein Nutzer im Onlineshop seine Bestellungen sehen - hier fragt die Anwendung über die API den aktuellen Stand ab.

APIs werden außerdem benötigt, wenn das System:

• Suchanfragen ausführen,
• Listen von Objekten abrufen,
• Einträge erstellen oder ändern,
• Daten löschen,
• Detailinformationen per ID abfragen,
• den Zeitpunkt der Server-Anfrage selbst bestimmen muss.

Webhooks sind für solche Aufgaben nicht gedacht - sie benachrichtigen über Ereignisse, erlauben aber meist keinen Abruf beliebiger Daten auf Anfrage.

In der Praxis ist eine kombinierte Lösung weit verbreitet: Der Webhook signalisiert eine Änderung, danach holt das System alle nötigen Details über die API.

Webhook, Polling und WebSocket

Der Webhook ist nicht die einzige Möglichkeit, um von anderen Diensten über Neuerungen informiert zu werden. Je nach Aufgabe kommen auch Polling oder WebSocket zum Einsatz.

Polling bedeutet, dass das System regelmäßig Anfragen an den Server stellt - etwa alle zehn Sekunden auf neue Nachrichten prüft. Das ist einfach umzusetzen, verursacht aber hohe Last, selbst wenn keine Änderungen auftreten.

Webhooks erzeugen keine dauerhafte Verbindung. Der Dienst sendet eine einzelne HTTP-Anfrage erst nach einem vordefinierten Ereignis. Das ist ideal für serverseitige Integrationen, Benachrichtigungen und Automatisierungen.

WebSocket wiederum baut eine dauerhafte bidirektionale Verbindung zwischen Client und Server auf, sodass beide Seiten jederzeit Daten austauschen können. Das ist nützlich für Chats, Online-Spiele, Handelsplattformen und andere Anwendungen mit Echtzeit-Kommunikation.

Mehr zum Prinzip dauerhafter Verbindungen finden Sie im Beitrag WebSocket einfach erklärt: So funktioniert die Echtzeit-Datenübertragung.

Die Wahl hängt von der Art der Daten ab: Für selbstbestimmte Anfragen ist die API ideal, zur automatischen Reaktion auf Ereignisse der Webhook, und für ständigen Datenfluss in Echtzeit der WebSocket.

Wie richtet man einen Webhook ein und was ist zu beachten?

Webhook-Endpoint erstellen

Damit ein Webhook funktioniert, benötigt das empfangende System eine öffentlich erreichbare URL - den sogenannten Webhook-Endpoint.

Der Entwickler erstellt einen Handler, der eingehende Daten empfängt, prüft und die gewünschte Aktion ausführt. Die URL wird dann in den Einstellungen des Quell-Systems hinterlegt.

Beispiel für einen Endpoint:

https://example.com/webhooks/payment

Wenn das relevante Ereignis eintritt, sendet der externe Dienst die Anfrage genau an diese Adresse.

Wichtig ist, dass der Endpoint aus dem Internet erreichbar ist und HTTPS unterstützt. Für lokale Entwicklung werden oft spezielle Tunnel- oder Testdienste genutzt, die temporär eine öffentliche Adresse für den Entwickler-PC bereitstellen.

Authentizität von Webhooks prüfen

Ein Webhook-Endpoint ist für eingehende Anfragen offen, daher dürfen eingehende Requests nicht blind vertraut werden.

Wenn Unbefugte die Webhook-Adresse kennen, könnten sie versuchen, gefälschte Ereignisse zu senden. Viele Dienste signieren Webhook-Anfragen daher mit einem geheimen Schlüssel.

Das empfangende System berechnet die Signatur selbst und vergleicht sie mit der vom Dienst gesendeten. Stimmen beide überein, kann sichergestellt werden, dass die Daten vom erwarteten Absender kommen und unterwegs nicht verändert wurden.

Zusätzlich können geheim gehaltene Tokens, Prüfung der HTTPS-Verbindung und IP-Adress-Filter genutzt werden, sofern der Dienst dies unterstützt.

Wiederholte Zustellung & Duplikaterkennung

Ein Webhook garantiert nicht, dass eine Anfrage immer beim ersten Mal verarbeitet wird. Server können zeitweise nicht erreichbar sein, Verbindungen abbrechen oder die Verarbeitung kann zu lange dauern.

Daher implementieren viele Plattformen einen Retry-Mechanismus: Antwortet der Endpoint mit einem Fehler oder zu spät, wird die Anfrage später erneut gesendet.

So kann dasselbe Ereignis mehrfach eintreffen. Die empfangende Anwendung muss Duplikate erkennen und darf identische Aktionen nicht mehrfach ausführen.

Das ist besonders bei Zahlungen wichtig - bei doppelter Benachrichtigung dürfen Guthaben oder Bestellungen nicht doppelt angelegt oder Waren erneut verschickt werden.

Hier hilft ein Ereignis-Identifier: Vor jeder Aktion prüft die Anwendung, ob diese ID schon verarbeitet wurde. Dieser Ansatz wird idempotente Verarbeitung genannt.

Logging und Rückgabecodes

Nach Erhalt des Webhooks sollte der Server einen HTTP-Statuscode zurückgeben - meist bestätigt ein Code im Bereich 200 die erfolgreiche Verarbeitung.

Antwortet der Server mit einem Fehler, wertet der externe Dienst die Zustellung als fehlgeschlagen und versucht die Übertragung erneut.

Aufwändige Aktionen sollten idealerweise nicht direkt im Webhook-Endpoint ausgeführt werden. Dauert eine Operation zu lange, kann das Ereignis zunächst geprüft, in eine Aufgabenwarteschlange gelegt und ein schneller Erfolgs-Response zurückgegeben werden. Die eigentliche Verarbeitung erfolgt dann asynchron.

Logging ist ebenfalls wichtig: Zeitpunkt des Ereignisses, Typ, ID und Ergebnis der Verarbeitung sollten gespeichert werden. Das erleichtert die Fehleranalyse und das Nachvollziehen von wiederholten Zustellungen.

Ein gut konfigurierter Webhook ist mehr als nur eine URL für POST-Anfragen. Eine zuverlässige Integration berücksichtigt Quell-Prüfung, Wiederholungsversuche, Dubletten, Fehler und temporäre Serverausfälle.

Fazit

Webhooks ermöglichen es einem System, ein anderes automatisch und ohne ständige API-Abfragen über Ereignisse zu informieren. Das ist besonders praktisch für Zahlungen, Benachrichtigungen, Service-Integrationen, Automatisierungen und andere Prozesse, bei denen eine schnelle Reaktion auf Änderungen erforderlich ist.

Der Hauptunterschied zwischen Webhook und klassischer API liegt in der Richtung der Kommunikation. Bei APIs fragt der Client aktiv Daten ab, beim Webhook sendet das Quell-System nach einem Ereignis eine Benachrichtigung. Beide Technologien ergänzen sich jedoch meist und schließen sich nicht aus.

Wenn das System Daten auf Anfrage benötigt, Suchen durchführt oder Objekte verändert, ist die API die richtige Wahl. Für automatische Reaktionen auf bestimmte Ereignisse eignet sich der Webhook. Und für dauerhaften, beidseitigen Datenaustausch in Echtzeit wird häufig WebSocket genutzt.

Bei der Einführung von Webhooks sind nicht nur das Senden von HTTP-Anfragen, sondern auch Sicherheit, Signaturprüfung, Wiederholungen, Dubletten-Schutz und eine saubere Fehlerbehandlung zu berücksichtigen. Gerade diese Details machen aus einem einfachen Webhook-Endpoint eine zuverlässige Integration zwischen Diensten.