Programmierung · Konzepte · Web

Was ist ein Webhook?

Du richtest eine Zahlung ein, und deine Anwendung reagiert in dem Moment, in dem das Geld eingezogen wird. Du pushst einen Commit, und ein Build startet von allein. Hinter dieser Unmittelbarkeit steckt fast immer ein Webhook. Dieser Leitfaden erklärt einfach, was ein Webhook ist, wie er sich von einem klassischen API-Aufruf unterscheidet, wie man ihn sicher empfängt und wo du schon heute auf ihn angewiesen bist.

Die kurze Definition

Ein Webhook ist eine automatische HTTP-Anfrage, die ein Dienst an eine von dir kontrollierte URL sendet, wenn ein Ereignis eintritt. Statt einen Dienst nach Neuigkeiten zu fragen, ist er es, der dich benachrichtigt, sobald es welche gibt.

Daher der Spitzname „umgekehrte API“. Bei einer klassischen API bist du der Client: du machst die Anfrage, der Server antwortet. Bei einem Webhook kehren sich die Rollen um — der Anbieter wird zum Client und dein Endpunkt ist der Server, den er aufruft.

Webhook vs. API-Polling

Vor den Webhooks war die übliche Art, auf dem Laufenden zu bleiben, das Polling: eine API auf einem Timer aufrufen („gibt es Neues?“) immer wieder. Das ist einfach, aber verschwenderisch — die meisten Aufrufe liefern nichts zurück, und es gibt immer eine Verzögerung zwischen dem Ereignis und der nächsten Prüfung.

• Polling — du fragst in einer Schleife. Viele nutzlose Anfragen, verzögerte Reaktion, einfach zu bauen.
• Webhook — der Dienst benachrichtigt dich einmal, sofort. Effizient und nahezu in Echtzeit, aber du musst einen Endpunkt betreiben, um ihn zu empfangen.

Wie es funktioniert, Schritt für Schritt

1. Du registrierst eine URL (deinen Endpunkt) beim Anbieter und wählst die Ereignisse, die dich interessieren.
2. Wenn ein solches Ereignis eintritt, sendet der Anbieter ein HTTP-POST an deine URL mit einem Body (oft JSON), der es beschreibt.
3. Dein Server liest den Inhalt, gibt schnell einen 2xx-Status zurück, um ihn zu bestätigen, und erledigt die eigentliche Arbeit danach.
4. Wenn dein Endpunkt offline ist oder einen Fehler zurückgibt, wiederholen die meisten Anbieter mit Backoff — daher die möglichen Duplikate.

Eine Zustellung sieht aus wie jede HTTP-Anfrage:

POST /webhooks/payments  HTTP/1.1
Host: deineapp.com
X-Signature: t=1718600000,v1=9f86d08...

{ "event": "payment.succeeded", "id": "pay_42", "amount": 1999 }

Beispiele, die du schon kennst

• Zahlungen — Stripe und PayPal senden einen Webhook, wenn eine Zahlung erfolgreich ist, fehlschlägt oder erstattet wird, damit deine App die Bestellung ohne Polling aktualisiert.
• Code-Hosting — GitHub und GitLab lösen einen Webhook bei Push, Pull Request oder Issue aus: so werden CI-Builds und Bots gestartet.
• Messaging — Slack, Discord und Chat-Plattformen nutzen eingehende Webhooks, um Nachrichten zu posten und deine App zu benachrichtigen.

Ihn sicher empfangen

Ein robuster Empfänger tut vier Dinge:

• Über HTTPS bedienen und POST akzeptieren; schnell mit einem 2xx antworten und dann asynchron verarbeiten.
• Die Signatur prüfen — die Anbieter signieren den Body (ein HMAC mit einem gemeinsamen Geheimnis). Ablehnen, was fehlschlägt.
• Idempotent sein — dasselbe Ereignis kann mehrmals ankommen; nutze die Ereignis-ID, damit die erneute Zustellung wirkungslos bleibt.
• Fehler ehrlich zurückgeben — wenn du nicht verarbeiten kannst, gib einen Nicht-2xx zurück, damit der Anbieter es erneut versucht, statt aufzugeben.

Webhooks brauchen einen immer online befindlichen Endpunkt mit einer öffentlichen HTTPS-URL — deshalb ist ein kleiner Server oder eine Cloud-Instanz das übliche Zuhause eines Webhook-Empfängers, und keine Maschine, die in den Ruhezustand geht.

Häufige Fragen

Was ist ein Webhook, einfach gesagt?

Ein Webhook ist eine automatische Nachricht, die ein Dienst in dem Moment an eine von dir kontrollierte URL sendet, in dem etwas passiert — zum Beispiel „eine Zahlung war erfolgreich“ oder „ein Commit wurde gepusht“. Statt den Dienst ständig zu fragen „gibt es Neues?“ (das Polling seiner API), ruft dich der Dienst mit einer HTTP-POST-Anfrage auf, sobald das Ereignis eintritt. Man spricht oft von einer „umgekehrten API“: bei einer klassischen API machst du die Anfrage; bei einem Webhook macht sie der Dienst an dich.

Was ist der Unterschied zwischen einem Webhook und einer API?

Sie sind verwandt, laufen aber in entgegengesetzter Richtung. Bei einer klassischen API (REST) sendest du eine Anfrage an den Anbieter, wann immer du Daten willst, und er antwortet. Bei einem Webhook sendet der Anbieter eine Anfrage an deinen Server, wenn ein Ereignis eintritt: die Daten werden dir nahezu in Echtzeit zugeschoben, ohne dass du etwas anfragst. Ein Webhook nutzt dieselbe HTTP-Mechanik wie eine API — der Anbieter spielt die Rolle des Clients und dein Endpunkt die des Servers.

Warum ein Webhook statt Polling?

Polling bedeutet, eine API in regelmäßigen Abständen aufzurufen, um auf Änderungen zu prüfen, was Anfragen verschwendet und eine Verzögerung zwischen dem Ereignis und deiner Reaktion hinzufügt. Webhooks schieben dir das Ereignis in dem Moment zu, in dem es eintritt: effizienter und viel näher an Echtzeit. Im Gegenzug musst du einen Endpunkt betreiben, der immer online ist, und Wiederholungen sowie doppelte Zustellungen handhaben.

Wie empfängt man einen Webhook sicher?

Stelle einen HTTPS-Endpunkt bereit, der POST akzeptiert, gib schnell einen 2xx-Status zurück, um den Empfang zu bestätigen, und verarbeite die Arbeit dann asynchron. Prüfe die Signatur, die der Anbieter sendet (ein HMAC des Bodys mit einem gemeinsamen Geheimnis), um die Echtheit zu bestätigen, und mache die Verarbeitung idempotent, da dasselbe Ereignis mehrfach zugestellt werden kann. Weise alles ab, was die Signaturprüfung nicht besteht.

Fazit

Ein Webhook ist die Art des Webs zu sagen „ruf uns nicht an, wir rufen dich an“: eine automatische HTTP-Anfrage, die ein Dienst an deinen Endpunkt sendet, sobald ein Ereignis eintritt. Das ist effizienter und viel näher an Echtzeit als das Polling einer API — zum Preis eines zuverlässigen Endpunkts, der Signaturen prüft, um ihn zu empfangen. Hast du sie einmal erkannt, wirst du Webhooks hinter fast jedem „es hat sich von allein aktualisiert“ der modernen Software sehen.