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-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-POST-Requests gesendet werden |
Zweck und Verwendung
Webhooks ermöglichen es ConSol CM über 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.
Die grundlegenden Schritte für die Informationsübertragung über 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:
Abbildung 66: Webhooks in ConSol CM
Beispiele für die Nutzung:
- Daten in ConSol CM anhand von Master-Daten, die in einem ERP-System gepflegt werden, aktualisieren.
- Eine Social-Media-Plattform integrieren, um Kundendaten nach ConSol CM zu importieren.
- Webformulare für die Erstellung von Vorgängen und das Hinzufügen von Inhalt verwenden.
Verfügbare Einstellungen für Webhooks
Unterstützte Content Types
Die HTTP-POST-Requests, die von der anfragenden Applikation gesendet werden, können folgende Content Types haben:
- application/json
- application/x-www-form-urlencoded
- multipart/form-data
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 folgende Einstellungen für Webhooks:
- Enabled: Markieren Sie diese Checkbox, um den Webhook zu aktivieren.
- IP-based filtering
- Markieren Sie die Checkbox Enabled, um IP-basierte Filterung als Security Provider zu aktivieren.
- Geben Sie die IP-Addressen in CIDR-Notation in das darunter liegende Feld ein, siehe Zulässiger Bereich der IP-Adressen.
- Secret tokens
- Markieren Sie die Checkbox Enabled, um Secret Token als Security Provider zu aktivieren.
- 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.
- Geben Sie den Namen des HTML-Headers für das gemeinsame Secret ein. Der Standardwert ist „SECRET_TOKEN“.
- Geben Sie die Secret Token in das darunter liegende Feld ein. Sie können in jede Zeile einen Token eingeben, siehe Secret Token.
Wenn beide Security Providers 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.
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.
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:
-
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.
-
Definieren Sie einen Security Provider, der die Requests prüft. Dies kann ein Bereich mit zulässigen IP-Adressen oder ein Secret Token sein, siehe Konfigurieren des Webhook-Services und Security Provider.
Die Service-URL, die die POST-Requests empfängt, ist:
https://<CM-Serveradresse>/intg/<Skriptname>/service
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. Der Name des Skripts (ohne die Erweiterung .groovy) ist der Name des Services, der in der URL, über die auf die Schnittstelle zugegriffen wird, enthalten ist.
Beispiel:
- Skriptname: myWebHook.groovy
- 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:
- Verarbeitung des Requests, siehe Verarbeiten der empfangenen Daten.
- Erzeugen der Response, siehe Erstellen der Response
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 - 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)
}
});
Code-Beispiel 43: Beispiel für das Zurückstufen der Session auf die Berechtigungen eines Benutzers
Konfigurieren des Webhook-Services
Die Konfigurationsseite ist unter der folgenden URL verfügbar:
https://<CM-Serveradresse>/intg/<Skriptname>/config
Sie müssen sich mit einem Administratorkonto anmelden. Auf der Konfigurationsseite können Sie den Webhook aktivieren und Security Provider definieren. Beide Schritte sind für die Verwendung des Webhooks obligatorisch. Details finden Sie in Security Provider.
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 im Skriptbereich der Web Admin Suite / des Admin Tools 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.intg.service.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 44: Beispielskript, das einen Webhook-Service implementiert