Entwicklungsumgebung

Entwicklungsumgebung
- HTTP-Server
- Webhook-Emulator

Entwicklungsumgebung

HTTP-Server

Für das Entgegennehmen der Webhooks wird ein HTTP-Server benötigt. Der HTTP-Server stellt die Schnittstelle zur Software des Konsumenten dar.

Der HTTP-Server muss in der Produktiv-Umgebung vom CareSuite-Server aus erreichbar sein.

Für die Entwicklung mit dem Webhook-Emulator reicht es aus, wenn der Webserver lokale Requests entgegennimmt.

Webhook-Emulator

Beim Webhook-Emulator handelt es sich um eine einfache Web-Anwendung mit der Webhooks auf Knopfdruck an einen Konsumenten im Netzwerk versendet werden können.

Es können also Webhooks ohne bestehende CareSuite-Installation simuliert werden.

Download und Installation

Die aktuellste Version des Webhook-Emulators befindet sich unter folgendem Link:

https://api.caresuite.ch/emulator.zip

Zur Installation einfach die ZIP-Datei entpacken und index.html im Webbrowser öffnen.

Funktionsweise

Im Feld Ziel-URL muss die URL des HTTP-Servers des Konsumenten eingegeben werden. Testweise kann als Empfänger auch der API-Testserver test.api.caresuite.ch eingetragen werden. Dieser Endpunkt sendet die erwarteten Beispiel-Antworten.
Im Feld Secret muss das Secret für die Kommunikation zur CareSuite-Installation eingetragen werden. Zu Testzwecken kann im Emulator ein selber gewähltes Secret verwendet werden. Das selbe Secret muss vom HTTP-Server verwendet werden, um die Signatur eines Webhooks zu validieren. In der letzendlichen Produktiv-Umgebung wird das Secret über die CareSuite-Oberfläche generiert und muss über die Konfigurationswerte beim Konsumenten hinterlegt werden können.
Über «Preset laden» können diverse Webhook-Vorlagen in den Editor geladen werden. Diese Vorlagen können nach belieben verändert werden.
Über den «Senden»-Button wird der Hash des Webhooks neu generiert. Anschliessend wird ein HTTP-Request an die eingetragene URL mit dem Webhook als JSON-Body gesendet. Die vom Konsumenten erhaltene Response wird dann unterhalb angezeigt.
Der «Senden»-Button enthält die sekundäre Option den Webhook absichtlich mit falschem Hash zu senden. Damit kann überprüft werden, ob ungültige Hashes korrekt erkannt werden.

Bei der Verwendung des Webhook-Emulators wird ein domainübergreifender Request versendet (CORS-Request, von localhost zum Konsumenten). Solche Requests werden vom Browser blockiert, sofern sie nicht explizit vom Konsumenten zugelassen werden.

Dies geschieht, in dem die korrekten Access-Control Header in der HTTP-Response mitgesendet werden.

Der Konsument muss folgende Header in der HTTP-Response mitsenden:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization

Siehe auch enable-cors.org für Beispiele, wie man CORS-Requests in diversen Servern zulässt.

Test-Suite

Es ist geplant eine automatisierte Test-Suite in den Webhook-Emulator zu integrieren. Diese Test-Suite soll auf Knopfdruck überprüfen, ob der HTTP-Server des Konsumenten korrekt auf die Webhooks reagiert.

Die korrekte interne Verarbeitung der Webhooks im System des Konsumenten muss selber sichergestellt werden.

Bis dieses Feature erstellt wurde können folgende Tests manuell ausgeführt werden:

Ungültiges Secret

GEGEBEN   es wird ein falsches Secret eingetragen
WENN      ein Webhook versendet wird
DANN      wird ein `400 Bad Request` Status-Code zurückgegeben

Siehe auch Webhooks → Signatur → Rückmeldung bei ungültigem Hash

Quittierung

GEGEBEN   es wird ein korrektes Secret eingetragen
WENN      ein Webhook versendet wird
DANN      wird ein `200 OK` oder `202 Accepted` Status-Code zurückgegeben

Siehe auch Webhooks → Quittierung

Entwicklungsumgebung