CareSuite Dokumentation

Quittierung

Umgehende Quittierung

Aktionen, die eine kürzere Ausführungszeit als 3 Sekunden haben, können direkt vom Konsumenten beim Empfang via HTTP-Response mit Status 200 OK quittiert werden.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "success": true
}

Im Fehlerfall muss die Antwort mit dem zutreffenden 4xx oder 5xx Statuscode gesendet werden. Fehlerdetails sind im Body der Response mitzusenden.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "success": false,
    "errors": [
        {
            "code": 404,
            "reason":  "NOT_FOUND",
            "message": "Element existiert nicht."
        }
    ]
}

Verzögerte Quittierung

Dauert die Ausführung einer Änderung länger als 3 Sekunden, ist der Webhook umgehend mit einem 202 Accepted Statuscode zu quittieren.

Die Änderungen im System können dann vorgenommen werden.

Sind alle Arbeiten abgeschlossen, muss das Ergebnis via HTTP-Request zurück an die CareSuite gemeldet werden. Dafür wird ein POST-Request an die im Webhook unter respond_to definierte URL versendet. Die URL des API-Servers muss vor dem Wert unter respond_to noch angefügt werden.

POST /api/v1/webhooks/8d8d52b6-ab21-4984-8abc-c5640b2e107e
Content-Type: application/json

{
  "success": true,
  "hash": "bf8ccfada9abee4ea8672c2e173e941c514a4496bcd97e4619551d1051278f7f"
}

Im Fehlerfall kann eine Fehlerbeschreibung mitgesendet werden.

POST /api/v1/webhooks/8d8d52b6-ab21-4984-8abc-c5640b2e107e
Content-Type: application/json

{
    "success": false,
    "hash": "e472e3aeae49b7c8eeaa0e7b369fddf41c1af404ff164c4c0fda12b9be429d3c",
    "errors": [
        {
            "code": 404,
            "reason":  "NOT_FOUND",
            "message": "Element existiert nicht."
        }
    ]
}

Signatur mit Hash

Um die Herkunft der verzögerten Antwort validieren zu können, muss auch diese mit einem Hash signiert werden.

Folgende Werte werden zu einem String zusammengesetzt. Alle Werte sind durch einen . voneinander zu trennen.

Wert Beispiel
id (aus URL) 8d8d52b6-ab21-4984-8abc-c5640b2e107e
success false
errors (falls vorhanden, als JSON) [{"code":404,"reason":"NOT_FOUND","message":"Element existiert nicht."}] 
POST /api/v1/webhooks/8d8d52b6-ab21-4984-8abc-c5640b2e107e
Content-Type: application/json

{
  "success": true
}

Aus dem obenstehenden Requests ergibt sich also folgender Prüfstring:

8d8d52b6-ab21-4984-8abc-c5640b2e107e.true

bzw. im Fehlerfall 

8d8d52b6-ab21-4984-8abc-c5640b2e107e.false.[{"code":404,"reason":"NOT_FOUND","message":"Element existiert nicht."}]

Aus diesem String wird nun ein Hash mit Schlüssel unter Verwendung von HMAC berechnet. Der verwendete Hash-Algorithmus ist sha256.

Hinweis zum JSON-Format

Es gelten die gleichen Formatierungsregeln wie bei den Webhooks. Siehe Webhooks → Signatur → Hinweis zum JSON-Format.

Beispielimplementierung

Für Beispielimplementierungen siehe Webhooks → Signatur → Generierung.

Verwendung von Testserver

Zu Testzwecken kann die URL des API-Testservers test.api.caresuite.ch für die respond_to Antworten verwendet werden. Dieser beantwortet die Anfrage. Wenn der mitgesendete Hash validiert werden soll, muss das verwendete Secret im HTTP-Header X-CS-DEBUG-SECRET mitgesendet werden.

Wichtig: Das Secret soll nur zu Entwicklungszwecken im Header gesendet werden. In der produktiven Umgebung darf es niemals mit dem Request mitgesendet werden.

Ein Beispiel-Request könnte wie folgt aussehen:

POST /api/v1/webhooks/8d8d52b6-ab21-4984-8abc-c5640b2e107e
Host: test.api.caresuite.ch
X-CS-DEBUG-SECRET: cE9lRcvbs3EUUuyN4AehZp3UwTwdmIdp64DHqbac1mFopGQLdKgqssG5PPImqVDl

{
    "success": false,
    "hash": "da211b06a5cef13fed4fedbb4a5f47ed164cca19875dacf75dd649185535aaea",
    "errors": [
        {
            "code": 404,
            "reason":  "NOT_FOUND",
            "message": "Element existiert nicht."
        }
    ]
}

Rückmeldung bei ungültigem Hash

Es wird die gleiche Antwort wie unter API → Signatur → Rückmeldung bei ungültigem Hash gesendet.

Beispiel für Verarbeitung

Im Folgenden wird eine Beispielverarbeitung eines Webhooks in Pseudecode beschrieben.

function process(webhook)
{
    if (generateHash(webhook) != webhook.hash) {

        return response(statusCode: 400, body: {
            success: false,
            messages : [{
                code    : 'invalid_hash',
                status_code  : 400,
                errors : 'Ungültiger Hash'
            }]
        });

    }

    if (isSlowAction(webhook)) {

        processAsync(webhook).then(sendResultTo(webhook.respond_to));

        return response(statusCode: 202, body: {success: true});

    } else {

        var result     = processDirectly(webhook);
        var httpStatus = result ? 200 : 422; 

        return response(statusCode: httpStatus, body: {success: result});

    }
}