Webhooks

Webhooks zur einfachen Integration externer Anwendungen in die PureLife Cloud.

Die PureLife Cloud verwendet Webhooks, um deine Anwendung zu benachrichtigen, wenn ein Sensor ein neues Ereignis meldet. Hierzu wird ein HTTP-POST-Request an eine hinterlegte URL gesendet.

Authentifizierung#

Die PureLife Cloud sendet mit jedem Request einen für jeden Webhook automatisch generierten Token. Über diesen kann verifiziert werden, dass das Request von der Cloud und nicht von einer anderen Partei gesendet wurde.

Der Token wird durch einen kryptografischen Zufallsgenerator erzeugt und ist 128-Bit lang. Um den Token einfach zu transferieren, ist er als mit z-base-32kodiert. Man erhält den Token auf der Übersichtsseite für Webhooks.

Die Cloud unterstützt verschieden Methoden zur Authentifizierung mittels des Tokens:

1. Bearer-Authentifizierung: Sendet den Token als Authorization: Bearer <token>-Header.
2. X-Api-Key (IETF RFC): Sendet den Token als X-Api-Key: <token>-Header. Der Aufbau des Header-Namen ist dabei an Standard-HTTP-Header angelehnt.
3. X-API-KEY (Case sensitive): Sendet den Token als X-API-KEY: <token>-Header. Kann verwendet werden, falls Ihre Anwendung zwischen Groß- und Kleinschreibung unterscheidet.
4. HTTP/Basic: Verwendet HTTP-Basis-Authentifizierung. Der Benutzername ist dabei immer purelife-cloud und das Passwort der Token.

Um ihre Anwendung zusätzlich abzusichern, sollten Verfahren wie Rate-Limiting und fail2Ban verwendet werden.

Signierung#

Die Cloud kann das Webhook-Request, das an deine Anwendung gesendet wird, optional signieren. Hierzu wird ein X-Purelife-Cloud-Signature-Header zu Request hinzugefügt. Somit kann verifiziert werden, dass das Request von der PureLife Cloud und nicht von jemand anderen gesendet wurde.

Um ihre Requests zu signieren, muss für den Webhook ein Secret hinterlegt werden.

Verifizierung#

Der Header X-Purelife-Cloud-Signature in jedem signierten Request enthält einen Hinweis auf den verwendeten Hash-Algorithmus und Signatur.

X-Purelife-Cloud-Signature: sha256=bdea638cc3e6f6ff70c1e6597f25020028d4975b82528ace6ca0688747f7c255

Die Cloud generiert Signaturen unter Verwendung eines Hash-basierten Authentifizierungscodes (HMAC) mit SHA256. Mit den folgenden Schritten ist eine Verifizierung möglich:

1. Teile den Header mit dem Symbol = in zwei Teile, um den verwendeten Hash-Algorithmus und die Signatur zu erhalten
2. Berechne einen HMAC mit einer SHA256-Hashfunktion. Verwende das hinterlegt Secret als geheimen Schlüssel und den Body des Requests als Nachricht.
3. Kodiere den errechneten HMAC als Hexadezimalwert
4. Vergleiche die Signatur der Kopfzeile mit der errechneten Signatur

Response#

Die Cloud erwartet von der angesprochenen Anwendung keine bestimmte Antwort, jedoch sollte die Anfrage schnell verarbeitet werden. Die Cloud wartet dabei maximal 3 Sekunden, bevor es das Request abbricht und erneut versucht. Sollte die Anwendung es nicht schaffen, eine Anfrage innerhalb von 3 Sekunden zu verarbeiten, wird eine Zustellung nicht möglich sein. Dies ist notwendig, da es bei der Anbindung vieler Sensoren zu vielen Anfragen kommen kann und ein Blockieren von der Cloud verhindert werden soll.

Status Codes#

Um die Fehleranalyse zu vereinfachen, ist es empfehlenswert, die Standard-HTTP-Status-Codes zu nutzen. Wichtig ist hierbei, dass für ein erfolgreich erkanntes Request der Status-Code 200 oder 201 gesendet wird, da es ansonsten dazu kommen kann, dass die Cloud die Anfrage als Fehler interpretiert und sie wiederholt.

Wiederholungsmechanismus#

Sollte es der Cloud nicht möglich sein, das Request erfolgreich an die Anwendung zuzustellen, wird versucht, die Anfrage zu wiederholen. Sollte es nach dem dritten Versuch nicht möglich sein, die Anfrage zuzustellen, wird sie verworfen. Die Abstände zwischen den Versuchen wird dabei durch einen exponentiellen Backoff-Algorithmus berechnet.

Verhalten bei Fehlern#

Sollte ein Fehler auftreten, wird dieser intern geloggt, jedoch nicht automatisch an sie weitergeleitet. Sollte der Verdacht eines Problems vorliegen, wende dich an deinen Administrator.

Aufbau des Requests#

Der Aufbau und die Formatierung kann pro Webhook eingestellt werden.

Siehe: Webhook API-Dokumentation

Verwendung#

Der Webhook kann als Account-Bot (für die Verwendung im Regelwerk) oder als Kunden-Bot (für eine unabhängige Verwendung) erstellt und verwendet werden.