Webhooks

Einführung in Webhooks in ConSol CM

Webhooks ermöglichen eine einfache Integration von ConSol CM mit externen Applikationen, wie Einkaufsapplikationen, Social-Media-Plattformen oder vom Kunden entwickelten Applikationen. Die Applikationen können über HTTP-GET-Requests oder HTTP-POST-Requests Daten an ConSol CM senden. ConSol CM verarbeitet die empfangenen Daten und sendet eine Antwort an die anfragende Applikation.

Konzepte, Begriffe und Definitionen

Konzept

Andere Begriffe

Definition

Webhook

 

Mechanismus, der die Kommunikation zwischen ConSol CM und externen Applikationen ermöglicht

Security Provider

Sicherheitsanbieter

Mechanismus, der überprüft, ob die vom Webhook empfangenen Daten von einer autorisierten Applikation kommen

Content Type

Inhaltstyp

Format der Daten, die mit HTTP-Requests gesendet werden

Zweck und Verwendung

Webhooks ermöglichen es ConSol CM über HTTP-GET-Requests oder HTTP-POST-Requests mit externen Applikationen zu kommunizieren. Das ConSol CM-Webhook-Modul stellt Services für solche Integrationen zur Verfügung. Sie können mehrere Applikationen gleichzeitig integrieren. Zudem werden Webhooks für Webformulare verwendet (siehe CM/Forms).

Mit Webhooks kann eine einzelne Aktion durchgeführt werden oder es können Informationen übertragen werden. Die grundlegenden Schritte für Nutzung von Webhooks sind:

Die folgende Abbildung zeigt das Zusammenspiel zwischen der externen Applikation und ConSol CM über POST-Requests:

Abbildung 32: Webhooks in ConSol CM

Beispiele für die Nutzung:

Verfügbare Einstellungen für Webhooks

Unterstützte Content Types

Die HTTP-Requests, die von der anfragenden Applikation gesendet werden, können folgende Content Types haben:

Die Response, die an die anfragende Applikation zurückgesendet wird, hat immer den Content Type application/json. Sie kann benutzerdefinierte Objekte der folgenden Typen enthalten:

Security Provider

Es gibt drei Security Provider für Webhooks:

Wenn sowohl die IP-basierte Filterung als auch Secret-Token konfiguriert sind, werden sie in folgender Reihenfolge überprüft:

Sie können API-Token alleine oder zusätzlich zur IP-basierten Filterung und Secret-Tokens verwenden.

Außer den Security Providern gibt es keine obligatorische Zugriffsvalidierung. Insbesondere gibt es keine auf einer Anmeldung basierende Authentifizierung, wie für Benutzer, die zusätzliche Zugriffsbeschränkungen erzwingt. Die Schnittstelle hat vollen Systemzugriff, sodass eine zusätzliche Absicherung über einen Proxy für die Verwendung in der Praxis verpflichtend ist.

Es wird dringend empfohlen, HTTPS als Kommunikationsprotokoll zu verwenden, wenn Sie Daten über einen ConSol CM-Webhook übertragen möchten.

API-Token

API-Token werden über Skript erzeugt. Sie sind mit dem Namen des Webhooks, ihrer Gültigkeit, der Anzahl der erlaubten Übermittlungen und frei definierbaren Kontextinformationen in der Datenbank gespeichert. Requests haben die Syntax <webhook URL>?token=<TOKEN>. Zuerst wird die Gültigkeit des Tokens geprüft und danach verarbeitet das Integrationsskript den Request.

Zulässiger Bereich der IP-Adressen

Der IP-basierte Filter verwendet eine Liste mit IP-Adressbereichen, die in CIDR-Notation (Classless Inter-Domain Routing) definiert sind. Ein gültiger Eintrag in dieser Notation ist eine IP-Adresse gefolgt von einem Schrägstrich, der diese von der Anzahl der Bits, mit denen die Subnetzmaske definiert ist, trennt. Das Beispiel 10.20.30.40/24 steht für die IP-Adresse 10.20.30.40 und die Subnetzmaske 255.255.255.0. Die Adressliste für die Servicekonfiguration erlaubt mehrere IP-Bereiche in dieser Notation. Jeder Eintrag muss in einer eigenen Zeile stehen.

Secret Token

Die Checkbox HMAC aktiviert die Validierung des Requests über einen obligatorischen Hash, der auf dem Token basiert. Der HMAC-Wert (Hash-based Message Authentication Code) wird aus der unverschlüsselten Payload und dem Secret Token abgeleitet. Dieser Code wird im Header des Requests übertragen und vom Server mithilfe des Secret Tokens entschlüsselt. Der einzige von ConSol CM unterstützte Hashing-Algorithmus ist SHA-1. MD5 wird nicht unterstützt.

Ein entsprechendes Hashing der Response wird aktuell nicht unterstützt.

Das Eingabefeld Header ermöglicht die Definition des HTTP-Header-Feldes, das für die Übertragung des gemeinsamen Secret Tokens verwendet wird. Der Standardwert ist SECRET_TOKEN, wobei empfohlen wird, diesen Wert zu ändern. Ein Name, der nicht der Standardname ist, kann die Sicherheit verbessern.

Das Skript kann in der Header-Map des HTTP-Requests auf das verwendete Token zugreifen. Diese enthält ein Feld mit dem Namen, der in der Webhook-Konfiguration unter Headers definiert ist.

Das Verhalten des Service basiert ausschließlich auf der Implementierung im entsprechenden Skript, d. h. die auf den angegebenen Token basierende Sicherheit muss implementiert werden und ist nicht systemimmanent.

Erstellen eines Webhooks

Zum Erstellen eines Webhooks sind folgende Schritte erforderlich:

  1. Schreiben Sie ein Skript des Typs Integration, in dem Sie die Logik des Webhooks implementieren. Dieses Skript muss die von der externen Applikation empfangenen Daten verarbeiten und eine Response an die Applikation senden. Siehe Schreiben des Integrationsskripts.

  2. Konfigurieren Sie den Webhook, indem Sie einen Security Provider definieren, der die Requests prüft. Dies kann ein API-Token, ein Bereich mit zulässigen IP-Adressen oder ein Secret Token sein, siehe Konfigurieren des Webhooks und Security Provider.

  3. Aktivieren Sie den Webhook, sobald er fertig konfiguriert ist, und Requests erhalten soll.

Die Service-URL, die die Requests empfängt, ist:

https://<CM-Serveradresse>/intg/<Skriptname>/service

Die Basis-URL ist in der System-Property cmas-core-server, url.webhooks gespeichert.

Schreiben des Integrationsskripts

Sie müssen ein Skript des Typs Integration erstellen, um die von der externen Applikation empfangenen Daten zu verarbeiten und eine Response an die Applikation zu senden. Dazu können Sie entweder auf der Seite Webhooks auf den Button Neuer Webhook klicken, oder auf der Seite Skripte auf den Button Neues Skript klicken und den Typ Integration auswählen. Der Name des Skripts ist der Name des Services, der in der URL, über die auf die Schnittstelle zugegriffen wird, enthalten ist. Daher darf der Skriptname keine Erweiterung .groovy haben.

Beispiel:

Zur Verarbeitung des Requests wird das Skript in einem administrativen Kontext ausgeführt, sodass es vollen Systemzugriff hat.

Das Integrationsskript besteht aus zwei Teilen:

Verarbeiten der empfangenen Daten

Der erste Schritt zur Verarbeitung der empfangenen Daten ist die Ermittlung des Content Types der Payload. Entweder wissen Sie bereits, welchen Content Type die anfragende Applikation verwendet, oder Sie überprüfen den Content Type im Skript:

Nach dem Ermitteln des Content Types können Sie die Daten verarbeiten, um Objekte in ConSol CM zu erstellen oder zu aktualisieren.

Erstellen der Response

Skripte des Typs Integration müssen ein Objekt der Klasse IntgServiceResponse zurückgeben, dass folgende Informationen enthalten kann:

Berechtigungen

Das Webhook-Skript wird mit Administratorberechtigungen ausgeführt. Dies bedeutet, dass auch alle im Skript durchgeführten Operationen mit diesen Berechtigungen ausgeführt werden. Falls dies nicht erwünscht ist, kann das Skript die Anmeldeinformationen eines Bearbeiters und Code enthalten, um die Session auf die Berechtigungen des Bearbeiters herunterzustufen. Dafür wird die Methode executeWithUserPermissions der Klasse SecurityTemplate verwendet.

Das folgende Code-Beispiel zeigt die Verwendung dieser Methode in einem Skript. Die Session wird auf die Berechtigungen des Benutzers zurückgestuft, der über das im JSON-Payload enthaltene Login und Passwort identifiziert wird. Dann wird mit diesen Berechtigungen eine Kundensuche nach dem Kunden mit der ID „12345“ durchgeführt.

import com.consol.cmas.common.security.template.SecurityCallbackWithoutResult;

import com.consol.cmas.common.security.template.SecurityTemplate;

import groovy.json.JsonSlurper

 

def jsonSlurper = new JsonSlurper()

def message = jsonSlurper.parseText(payload);

SecurityTemplate.executeWithUserPermissions(message.login, message.password, new SecurityCallbackWithoutResult() {

@Override

public void doInSecurityContextWithoutResult() {

unitService.getById(12345)

}

});

Code-Beispiel 46: Beispiel für das Zurückstufen der Session auf die Berechtigungen eines Benutzers

Für die Zeichen " $ : und \, die in den Passwörtern enthalten sein können, müssen umgekehrte Schrägstriche als Escape-Zeichen verwendet werden.

Konfigurieren des Webhooks

Sie können den Webhook im Detailbereich der Seite Webhooks konfigurieren. Sie müssen mindestens einen Security Provider für den Webhook definieren. Sobald der Webhook Requests erhalten soll, müssen Sie ihn aktivieren, indem Sie auf das Icon Aktivieren klicken.

Testen des Services

Ein einfacher Weg zum Testen Ihres Services ist die Verwendung eines REST-Plugins in Ihrem Browser:

Die Response wird als JSON zurückgesendet. Wenn der Vorgang gefunden wurde, enthält die Response die im Skript definierten Vorgangsinformationen. Andernfalls wird die definierte Fehlermeldung zurückgesendet.

Alternativ können Sie den Service auch mit CURL testen: 

# Linux:

curl -X POST https://myserver.consol.de:8080/intg/myWebHook/service //

-H 'content-type: application/json' //

-d '{"ticket": "100200"}'

 

# Windows (note the different quoting/escaping for the -d option):

curl -X POST https://myserver.consol.de:8080/intg/myWebHook/service //

-H "content-type: application/json" //

-d "{\"ticket\": \"100200\"}"

Die Payload des Requests ist in diesem Beispiel der Wert der Option -d.

Das folgende Beispiel zeigt die vom Skript erzeugte Response, die an die anfragende Applikation zurückgesendet wird:

{

"status" : "OK" ,

"ticket" : "100200" ,

"subject" : "New Ticket for Resource 3" ,

"engineer" : "Susan ServiceDesk"

}

Code-Beispiele

Das folgende Beispiel zeigt die Implementierung eines Services mit dem Namen myWebHook. Das Skript heißt myWebHook.groovy und ist auf der Seite Skripte der Web Admin Suite gespeichert. Es gibt ein JSON-Objekt mit Vorgangsnummer, Thema und dem zugewiesenen Benutzer als Antwort auf einen Request mit der Vorgangsnummer zurück.

import com.consol.cmas.common.service.intg.IntgServiceResponse

import groovy.json.JsonSlurper

import groovy.json.JsonOutput

import com.consol.cmas.common.service.TicketService

 

def jsonSlurper = new JsonSlurper()

def message = jsonSlurper.parseText(payload)

def ticketname

def ticketsubject

def engineername

def OK = false

if (message.ticket) {

ticket = ticketService.getByName(message.ticket)

if (ticket) {

ticketname = message.ticket

ticketsubject = ticket?.getSubject()

if (ticket.engineer) {

engineername = ticket.engineer.getFirstname() + " " + ticket.engineer.getLastname()

}

OK = true

}

}

def response = new IntgServiceResponse()

if (OK) {

response.httpStatusCode = 200

response.body = JsonOutput.toJson([ticket: ticketname, subject: ticketsubject, engineer: engineername]) // optional

} else {

response.httpStatusCode = 404

response.httpHeaders = ['Content-Language':'en', 'Warning':'Required oject not found']

}

return response

Code-Beispiel 47: Beispielskript, das einen Webhook-Service implementiert

Das folgende Beispiel zeigt, wie ein GET-Request mit Token in einer E-Mail zum Genehmigen eines Vorgangs verwendet werden kann. Sie müssen folgende Schritte durchführen:

  1. Erstellen Sie in einem Skript einen Link zum Webhook-Endpunkt, z. B. in dem Aktivitätsskript, das die E-Mail mit dem Genehmigungslink erzeugt. Mit der Methode linkTo.webhookWithToken können Sie einen Link mit Token generieren. Der Beispielcode erzeugt einen Link mit einem Token, das 1 Tage lang gültig ist und aus zwei Parametern bestehende Kontextinformationen enthält:

    linkTo.webhookWithToken('MyWebhook', 1, [param1: val2, param: 'val2'] )

    Die generierte URL ist http://localhost:8080/intg/MyWebhook/service?token=713f707f-6dd2-4247-bf70-7f6dd2f2476d

  2. Verarbeiten Sie die eingereichten Informationen im Integrationsskript des Webhooks. Sie können folgendermaßen auf die Parameter zugreifen:

    log.info context.param1

Damit die Methode linkTo funktioniert, müssen Sie die System-Property cmas-core-server, url.webhooks setzen.