Webhook Feature in Bot Formularen

Dieser Artikel beschreibt das Webhook-Feature und erklärt im Detail, wie die Verwendung der Webhooks erfolgt.

Allgemeine Informationen

Die Verwendung des Webhook-Features ermöglicht die Nutzung von APIs und so das Abrufen und Übermitteln von Daten. Die Verwendung des Features ist als Aktion in Formularen möglich. Werden Webhooks in Formularen verwendet, ist die Übermittlung entgegengenommener Daten an ein anderes System oder die Durchführung einer Authentifizierung möglich.

Alle wichtigen Einstellungen erfolgen auf der Webhook-Konfigurationsseite:

Angabe der Ziel-URL
Definition der HTTP-Methode (POST, GET, etc.)
Konfiguration benutzerdefinierter Header oder Body als JSON

Der Zugriff auf den Dialogkontext ist stets via Templates (Handlebars) möglich, um z. B. abgefragte Daten wie Kundennummern oder andere benötigte Informationen an die API zu übermitteln. Gleichzeitig ist die Definition verschiedener Schritte im Formular ist möglich, so ist z.B. die Prüfung einer eingegebenen Kundennummer via Webhook möglich. Das Ergebnis der Abfrage ist im Dialogkontext gespeichert, sodass ein Zugriff auf diese Information in den Folgeschritten möglich ist.

Webhook Einstellungen

Um die Kommunikation mit einer API optimal zu gestalten, ist die Konfiguration mehrerer Elemente des Webhooks möglich:

Kontextname: Der Kontextname ermöglicht das Speichern der Antwort des Webhooks im Dialogkontext. Die Verwendung des Kontexts über Handlebars, z. B. , ist möglich.
URL: Hier erfolgt die Angabe der Ziel-URL des Webhooks. Sie ist die Adresse der API, mit der der Webhook kommuniziert. Es kann sich um eine interne oder externe API handeln.
Methode: Die HTTP-Methode, ist die Methode nach der der Webhook die Daten sendet. Übliche Methoden sind POST (zum Übermitteln von Daten) und GET (zum Abrufen von Daten). In manchen Fällen sind auch andere Methoden wie PUT oder DELETE möglich.
Headers: Das Hinzufügen benutzerdefinierter Header, die bei der Anfrage an die API übermittelt werden, ist möglich. Ein typisches Beispiel ist der X-Api-Key zur Authentifizierung der Anfrage. Hier ist die Konfiguration beliebig vieler Header möglich, um die Anforderungen der Ziel-API zu erfüllen.
Body: Es gibt verschiedene Body-Optionen, wie Default oder Custom. Mit der Option Custom ist die Individuelle Gestaltung des Bodys möglich, sodass spezifische Daten an die API gesendet werden können. Dies ist besonders nützlich, wenn komplexere Datenstrukturen übertragen werden müssen. Die Konfiguration des Bodys erfolgt im JSON-Format und enthält die Daten, die an die API übermittelt werden sollen. Der Zugriff auf den Dialogkontext ist über von Handlebars möglich, um dynamisch Informationen wie Kundendaten oder Antworten zu integrieren.
Authentifizierung: Falls für den Webhook eine HTTP-Basic-Authentifizierung erforderlich ist, können Nutzername und Passwort angegeben werden. Alternativ kann auch ein Token-basiertes Authentifizierungssystem (zB Bearer Token) verwendet werden, indem entsprechende Header gesetzt werden.

Beispiel: Übermittlung vom Zählerstand

Ein Kunde möchte seinen Zählerstand an den Stromdienstleister übermitteln. Dazu wird ein Formular genutzt, das die relevanten Daten abfragt. Ein Webhook übermittelt die Daten in das Backend.

Ablauf:

Eingabe von Kundendaten: Der Kunde gibt seine Kundennummer und sein Geburtsdatum an. Das Geburtsdatum dient als Legitimation zur Änderung im Backend. Stimmt die Kundennummer nicht mit dem Geburtsdatum überein, wird der Vorgang abgebrochen.
Authentifizierung: Die Kundendaten werden über einen ersten Webhook-Endpunkt “Auth” an das Backend gesendet, um die Berechtigung des Kunden zu prüfen. Dieser Schritt stellt sicher, dass die eingegebenen Daten korrekt sind und der Kunde autorisiert ist, Änderungen vorzunehmen. Beispiel für die Webhook-Konfiguration:
- URL: https://api.stromdienstleister-xyz.de/v1/customer/authenticate
- Methode: POST
- Kontextname: auth_response
- Headers:
```
{
  "X-Api-Key": "<Ihr-Api-Key>",

  "Content-Type": "application/json"

}
```
- Body:
```
{

  "customerNumber": "",

  "birthDate": ""

}
```
- Antwort: Das Backend gibt eine Antwort zurück, die angibt, ob der Kunde authentifiziert wurde. Beispiel:
```
{

  "auth": true,

  "customerId": "123456",

  "message": "Authentication successful"

  "jwt": "the jwt token"

}
```
Zählerstand eingeben: Der Kunde trägt den aktuellen Zählerstand ein und sendet das Formular ab.
- JWT zur Authentifizierung: Zusätzlich zum API-Key kann ein JWT (JSON Web Token) für die Authentifizierung verwendet werden. Das JWT wird im Header als Authorization hinzugefügt und stellt sicher, dass die Anfrage von einem berechtigten Benutzer kommt.
  
  Zugriff erfolgt über den im vorherigen Webhook definierten Kontextname.
- URL: https://api.stromdienstleister-xyz.de/v1/customer/update
- Methode: POST
- Kontextname: customer_update_response
- Headers:
```
{

 "Authorization": "Bearer ",

 "Content-Type": "application/json" 

}
```
- Body:
```
{

  "customerNumber": "",

  "updateType": "meterReading",

  "value": ""

}
```
- Antwort (Beispiel):
```
{

  "status": "success",

  "updateId": "78910",

  "message": "Update successfully processed"

}
```

Sicherheit und Schutz vor Missbrauch (Empfehlung):

API-Key und JWT: Die Nutzung eines API-Keys in Kombination mit einem JWT sorgt für eine zusätzliche Sicherheitsebene. Der API-Key wird im Header mitgesendet, während das JWT sicherstellt, dass die Anfrage authentifiziert ist und innerhalb einer bestimmten Zeitspanne erfolgt.
TLS/SSL-Verschlüsselung: Alle Datenübertragungen sollten über HTTPS erfolgen, um sicherzustellen, dass die Daten während der Übertragung verschlüsselt sind und nicht von Dritten abgefangen werden können.

Dieses Beispiel zeigt, wie flexibel Webhooks in unserer Plattform genutzt werden können, um kundenspezifische Anforderungen zu erfüllen und mit bestehenden Systemen zu kommunizieren. Die Nutzung von Handlebars ermöglicht es, dynamisch auf Informationen zuzugreifen und diese effizient in die Webhook-Anfragen zu integrieren.

Falls Sie weitere Fragen zur Nutzung des Webhook-Features oder zur Konfiguration haben, steht unser Customer Success Team ihn zur Verfügung.