Zum Hauptinhalt springen

Webhooks

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. 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 externe Applikation sendet einen HTTP-Request an den Webhook-Service in ConSol CM.
  • Der Request wird vom Webhook verarbeitet. Die Funktionalitäten des Services werden in einem Skript implementiert.
  • Die Response wird zurück an die anfragende Applikation gesendet. Dieses verarbeitet die Response.

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

Webhooks_DE.png

Beispiele für die Nutzung:

  • Daten in ConSol CM anhand von Master-Daten, die in einem ERP-System gepflegt werden, aktualisieren.
  • Webformulare für die Erstellung von Vorgängen und das Hinzufügen von Inhalt verwenden.
  • E-Mails mit Links zur Genehmigung senden.

Verfügbare Einstellungen für Webhooks​

Grundlegende Einstellungen​

Der Name des Webhooks ist der Name des Integrationsskripts ohne dessen Dateiendung. Die URL basiert ebenfalls auf dem Namen und kann nicht verändert werden. Sie können folgende grundlegende Einstellungen vornehmen:

  • Methode: Pflichtangabe. Wählen Sie zwischen GET und POST, um die Art des Requests festzulegen.
  • Beschreibung: Optional. Freitextfeld zur internen Dokumentation des Webhooks.

Im Abschnitt Verwendungsbeispiele sehen Sie die CURL-Befehle, mit denen Sie den Webhook aufrufen können. Das Beispiel basiert auf der URL des Endpunktes, der ausgewählten Request-Art und der Sicherheit.

Unterstützte Content Types​

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

  • application/json (nur POST-Requests)
  • application/x-www-form-urlencoded (GET- und POST-Requests)
  • multipart/form-data (nur POST-Requests)

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:

  • httpStatusCode
  • httpHeaders
  • body

Security Provider​

Es gibt drei Security Provider für Webhooks:

  • API-Token: Markieren Sie die Checkbox Aktiviert, um API-Token als Security Provider zu aktivieren.
  • IP-basierte Sicherheit:
    1. Markieren Sie die Checkbox Aktiviert, um IP-basierte Filterung als Security Provider zu aktivieren.
    2. Geben Sie die IP-Adressen in CIDR-Notation in das darunter liegende Feld ein, siehe Zulässiger Bereich der IP-Adressen.
  • Sicherheit über Secret Token:
    1. Markieren Sie die Checkbox Aktiviert, um Secret Token als Security Provider zu aktivieren.
    2. Markieren Sie die Checkbox HMAC, um einen sicheren Hashwert für die Authentifizierung der Nachricht zu verwenden. Wird nur für die Content Types application/json und application/x-www-form-urlencoded unterstützt.
    3. Geben Sie den Namen des HTML-Headers für das gemeinsame Secret ein. Der Standardwert ist "SECRET_TOKEN".
    4. Geben Sie die Secret Token in das darunter liegende Feld ein. Sie können in jede Zeile einen Token eingeben, siehe Secret Token.

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

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

  • Zuerst wird die IP-Adresse überprüft. Wenn sie sich im zugelassenen Bereich befindet, wird der Request weiter verarbeitet.
  • Wenn sich die IP-Adresse nicht im zugelassenen Bereich befindet, wird danach das Secret Token geprüft. Wenn es korrekt ist, wird der Request ebenfalls weiter verarbeitet.
  • Wenn keines der beiden Kriterien erfüllt ist, wird der Request mit einer Meldung Autorisierung fehlgeschlagen zurückgewiesen.
warnung

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.

warnung

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:

  • Skriptname: myWebHook
  • Service-URL: https://<CM-Serveradresse>/intg/myWebHook/service

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:

  • application/json: Die Payload ist ein Objekt der Klasse String im JSON-Format.
  • application/x-www-form-urlencoded: Die Payload ist ein Objekt der Klasse MultiValueMap.
  • multipart/form-data: Die Payload ist ein Objekt der Klasse MultipartData.

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:

  • httpStatusCode: Optional. Definiert den HTTP-Statuscode. Wenn nicht angegeben, werden folgende unterstützte Standard-Statuscodes verwendet:
    • 200 (OK)
    • 401 (Unauthorized): Ein oder mehrere Security-Provider sind aktiviert, aber die vom Client gelieferten Daten entsprechen nicht den erwarteten Daten (z. B. falscher Token oder falsche IP-Adresse)
    • 404 (Not Found): Es wurde kein Skript für einen Webhook mit dem angegebenen Namen gefunden / der Webhook ist deaktiviert / es wurde kein Security-Provider für den Webhook aktiviert.
    • 405 (Method Not Allowed): Eine andere HTTP-Method als POST oder GET
    • 500 (Internal Server Error): Serverseitige (ConSol CM) Probleme / Ausnahmen
  • httpHeaders: Optional. Definiert den Response-Header. Nur erforderlich, wenn Sie einen speziellen httpHeader definieren möchten, d. h. einen Header, der nicht in den unterstützten Standard-Headern enthalten ist.
  • body: Optional. Definiert den Inhalt der Response. Wenn nicht angegeben, ist die Response leer. Dies ist das Objekt, das einen JSON-Ausdruck enthalten kann, siehe Code-Beispiel.

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)
    }
});

info

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:

  • Setzen Sie den erforderlichen Content Type im Header, z. B. application/json.
  • Geben Sie den Request-Inhalt im Body in der für den Content Type passenden Syntax an, z. B. {"ticket": "100200"} zum Abrufen eines Vorgangs über JSON.
  • Senden Sie einen POST-Request an die Service-URL: https://<CM-Serveradresse>/intg/<Skriptname>/service

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-Beispiel​

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

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
info

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