Webhooks: Der sichere Rückruf mit HMAC

Das 9. Kapitel des O'Reilly ebooks "Learning API Styles" bietet eine detaillierte Einführung in das Thema **Webhooks**, ein Konzept für ereignisgesteuerte Schnittstellen (APIs). Ein Webhook ermöglicht es einem Dienst (Source), Nachrichten an einen anderen Dienst (Destination) zu senden, ohne dass dieser die Nachricht explizit anfordern muss.
Webhooks werden auch als *HTTP-Push-APIs**, **HTTP-Callbacks* oder *Reverse-APIs* bezeichnet. Sie basieren auf dem Callback-Konzept: Ein Dienst hinterlegt bei einem anderen eine „Rückrufadresse“ (HTTP-Endpunkt), um bei bestimmten Ereignissen benachrichtigt zu werden.
Im Gegensatz zum klassischen „Polling“, bei dem ein Client ständig Daten beim Server abfragt, schiebt (pusht) der Quell-Dienst die Daten beim Eintreten eines Ereignisses direkt zum Ziel-Dienst.
Die Integration erfolgt durch die Registrierung einer Callback-URL. Sobald ein Ereignis eintritt, sendet die Quelle einen *HTTP-POST-Request* (selten GET) mit den Ereignisdaten (meist JSON oder XML) an diese URL. Der Empfänger muss den Erhalt der Nachricht mit einem Erfolgsstatus-Code (z. B. HTTP 200 OK) bestätigen.
Webhooks werden je nach Sichtweise als *eingehend (incoming)* oder *ausgehend (outgoing)* klassifiziert. Wenn eine Nachricht bei einem Dienst ankommt, ist es ein eingehender Webhook; verlässt sie ihn, ist es ein ausgehender.
*HMAC (Hash-based Message Authentication Code):* Da Webhooks über das öffentliche Internet gesendet werden können, nutzen sie oft HMAC zur Sicherstellung der **Integrität und Authentizität**. Dabei wird ein gemeinsamer geheimer Schlüssel (Shared Secret) verwendet, um die Nachricht zu signieren und auf Empfängerseite zu verifizieren.
Durch die Verwendung von Zeitstempeln in den Headern kann verhindert werden, dass alte Nachrichten erneut gesendet werden (Replay-Attacken).
Da es lange keinen einheitlichen Standard gab, versucht das Projekt „standard-webhooks“, die Implementierung (Sicherheit, Zuverlässigkeit, Interoperabilität) industrieübergreifend zu normalisieren.
*OpenAPI-Spezifikation (OAS):* Ab Version 3.0 unterstützt OAS die Dokumentation von Webhooks über die Felder `webhooks` und `callbacks`. Dies ermöglicht es Entwicklern, die Struktur der gesendeten Payloads und die erwarteten Antworten maschinenlesbar zu definieren.
Werkzeuge wie der *Swagger Editor* helfen dabei, diese Spezifikationen zu visualisieren und zu validieren.

#webhooks #oreilly #api