Was ist ein Webhook?

Einfach erklärt

Sie warten auf ein Paket. Statt stündlich die Sendungsverfolgung aufzurufen, bekommen Sie eine Nachricht, sobald es zugestellt ist. Ein Webhook ist diese Nachricht unter Programmen. Tritt ein bestimmtes Ereignis ein, schickt das eine Programm sofort eine kurze Meldung an eine vorher hinterlegte Internetadresse des anderen. Über eine API fragt ein Programm nach, über einen Webhook wird es benachrichtigt.

Wofür das im Betrieb gut ist

• Ein abgeschlossenes Wartungsprotokoll landet sofort in der Dokumentenablage.
• Eine neue Reklamation im Ticketsystem erzeugt eine Nachricht im Team-Chat.
• Ein neuer Eintrag in der Kundendatenbank stößt eine Begrüßungsmail an.

Oft nimmt eine Workflow-Automatisierung den Webhook entgegen und erledigt die weiteren Schritte.

Worauf Sie achten sollten

Die Empfangsadresse ist aus dem Internet erreichbar. Damit niemand gefälschte Meldungen einschleust, unterschreibt der Absender jede Meldung mit einem gemeinsamen Geheimnis und der Empfänger prüft diese Unterschrift. Ihr IT-Dienstleister richtet das ein. Zieht ein Programm auf eine neue Adresse um, müssen alle Webhooks angepasst werden, die dorthin zeigen.

Was ein Webhook nicht leistet

Ein Webhook ist kein Einschreiben. Ist der Empfänger gerade nicht erreichbar, versucht der Absender es je nach Programm einige Male erneut oder gar nicht. Danach kommt die Meldung nicht mehr an. Wichtige Abläufe brauchen deshalb eine Kontrolle, ob alles angekommen ist.

Ablauf einer Zustellung

Ein Webhook beruht auf gewöhnlichem HTTP. Absender und Empfänger müssen sich nur über URL, Ereignisse, Datenformat und Geheimnis einig sein. Bei einem Ereignis sendet der Absender eine HTTP-Anfrage an die hinterlegte URL, in der Regel POST mit JSON-Inhalt. Der Empfänger bestätigt mit einem Status 2xx. GitHub etwa erwartet die Antwort innerhalb von 10 Sekunden und empfiehlt, die eigentliche Verarbeitung über eine Warteschlange anzustoßen. Ein Webhook aus Zammad sieht so aus:

POST /hooks/reklamation HTTP/1.1
Host: automation.ihre-firma.de
Content-Type: application/json
User-Agent: Zammad User Agent
X-Zammad-Trigger: Neue Reklamation
X-Zammad-Delivery: 3f6c0a9e…
X-Hub-Signature: …

{"ticket": {"number": "31045", "title": "Pumpe defekt", …}, "article": {…}}

Signatur prüfen

Der Absender bildet mit einem gemeinsamen Geheimnis einen HMAC nach RFC 2104 über den Inhalt der Anfrage. GitHub verwendet HMAC-SHA256 im Header X-Hub-Signature-256 mit dem Präfix sha256=, Zammad HMAC-SHA1 im Header X-Hub-Signature. Der Empfänger rechnet über die Rohdaten nach, bevor er das JSON einliest, und vergleicht in konstanter Zeit statt mit ==. Die Signatur verschlüsselt nichts. Die Übertragung gehört deshalb über HTTPS.

openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" < body.json

Typische Fehler

• Signatur nicht geprüft. Wer die URL kennt, kann beliebige Ereignisse einspielen.
• Verarbeitung vor der Antwort. Dauert sie länger, als der Absender wartet, gilt die Zustellung als gescheitert. Wiederholt er sie, entstehen ohne Abgleich der Zustell-ID (X-GitHub-Delivery, X-Zammad-Delivery) doppelte Vorgänge. Bei GitHub bleibt diese ID auch bei einer erneut angeforderten Zustellung gleich.
• Alte Adresse nach einem Umzug. Die Meldungen laufen ins Leere, oft ohne dass es jemand bemerkt.
• Fehlgeschlagene Zustellungen nicht beobachtet. Baserow etwa wiederholt fehlgeschlagene Aufrufe nur begrenzt oft und führt ein Protokoll der Aufrufe. Dort zeigt sich, was nicht ankam.
• Empfänger hinter einer Anmeldung. Der Absender kann sich nicht anmelden und erhält 401 oder eine Login-Seite.

Prüfen

Ohne gültige Signatur muss der Empfänger ablehnen:

curl -i -X POST https://automation.ihre-firma.de/hooks/reklamation \
  -H "Content-Type: application/json" -d '{"test": true}'

Mit korrekt berechneter Signatur muss er mit 2xx antworten. Danach im Zustellprotokoll des Absenders prüfen, ob echte Ereignisse ankommen.