Webhooks anwenden und konfigurieren

Webhooks ermöglichen die Kommunikation zwischen verschiedenen Anwendungen in Echtzeit. Dabei sendet ein Server (Absender) automatisch eine HTTP-Anfrage an einen anderen Server (Empfänger). Im Kontext von moinAI bedeutet dies, dass im Chat erhobene Daten an ein externes System übermittelt oder Informationen von dort abgerufen werden, um sie den Nutzer:innen direkt im Chat-Widget anzuzeigen.

Voraussetzungen für die Einsatz eines Webhooks sind ein bereits aufgesetztes Formular oder ein KI-Agent im Hub und eine ereichbare Ziel-URL (API-Endpunkt) des externen Systems.

1. Nutzen und Funktionsweise
2. Webhook erstellen
   2.1 Technische Gestaltung
   2.2 Erweiterte Optionen (Cookies & Authentifizierung)
   2.3 Webhook-Aktionen vor der Ausführung
3. Verwendung im Chatbot
   3.1 Webhooks als KI-Aktion
   3.2 Webhooks in Formularen
4. Testen und Validierung
5. Praxisbeispiele

1. Nutzen und Funktionsweise

Der Einsatz von Webhooks erlaubt es, den KI-Chatbot nahtlos mit Drittanbieter-Systemen wie z. B. CRM-Tools, Produktdatenbanken und Shopsysteme zu verbinden. Dies schafft folgende Vorteile:

• Automatisierung: Prozesse wie Terminbuchungen oder Bestellstatus-Abfragen erfolgen unmittelbar im Dialog, wodurch fallabschließende Unterhaltungen ermöglicht werden
• Flexibilität: Beliebige REST-Webhooks können ohne Code-Anpassungen integriert werden.

• Kontextbezug: Informationen aus der laufenden Unterhaltung fließen direkt in die API-Abfrage ein, z. B. Kundenstatus, aktuelle Unterseite oder Produktinteresse.

2. Webhook erstellen

1. Der Zugriff auf die Übersicht erfolgt im Hub über den Menüpunkt Integrationen → Webhooks (Push).
2. Mit der Schaltfläche Bearbeiten öffnet sich die Liste der bestehenden Webhooks.
3. Über den Button Webhook erstellen lässt sich eine neue, leere Maske öffnen.
   
   
4. Bestehende Webhooks können über das Stift-Symbol angepasst werden.
   
5. Mit einem Klick auf den Button Veröffentlichen unten/oben rechts im Webhook-Editor ist der Webhook in der Preview und Live verfügbar und kann mit KI-Agenten oder Formularen verknüpft werden.

2.1 Technische Gestaltung

In der Editier-Ansicht werden die Basisdaten der Schnittstelle festgelegt.

1. Namen auswählen: Ein individuell gewählter Name, der zur internen Unterscheidung im Hub dient. Der Name kann problemlos jederzeit geändert werden.
2. Kontextnamen bestimmen: Unter diesem Namen wird die Antwort der API im Dialog gespeichert. Die Verwendung des Kontextnamen andernorts als Verweis, z. B. über Handlebars, ist ebenfalls möglich. Aus diesem Grund sollte der Name möglichst konstant bleiben, da sonst jede Verknüpfung eine manuelle Anpassung benötigt.
3. Ziel-URL eintragen: Die API-Adresse, an welche die Daten gesendet werden. Es kann sich um eine interne oder externe API handeln. Auch hier können Handlebars genutzt werden, sodass die URL nicht starr ist, sondern dynamisch genutzt werden kann.
4. Methode festlegen: Festlegung der HTTP-Methode, nach welcher der Webhook die Daten sendet. Standardmäßig wird POST zum Senden von Daten oder GET zum Abfragen genutzt.

2.2 Optional: Erweiterte Optionen (Cookies & Authentifizierung)

Für spezialisierte Anforderungen bietet der Editor zusätzliche Steuerungsmöglichkeiten:

• Headers anpassen: Über Feld hinzufügen können benutzerdefinierte Header (z. B. content-type: application/json), die bei der Anfrage an die API übermittelt werden, hinterlegt werden. Alternativ kann über Vorlage verwenden ein Standard-Set geladen werden. 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 die Optionen Default, Custom und No Body.

• • Default: Bei dieser Einstellung werden die zu versendenden Daten automatisch durch das Formular vorgegeben. Der KI-Chatbot übermittelt hierbei alle im aktuellen Formularschritt erhobenen Angaben als standardisiertes Datenpaket. Dies ist eine zeitsparende Lösung, sofern das Zielsystem die moinAI-Standardstruktur verarbeiten kann.

  • No Body: Diese Option wird gewählt, wenn für die Anfrage kein Nachrichteninhalt erforderlich ist. Dies ist der Standard für GET-Anfragen, bei denen Daten ausschließlich über die URL abgerufen werden.

  • Custom: Mit dieser Option 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. Mithilfe von Handlebars kann hierbei gezielt auf Informationen aus dem Dialogkontext zugegriffen werden, um dynamische Informationen wie Kundendaten oder Antworten zu integrieren.

• Verwendung von Cookies: Durch Aktivierung dieser Option werden Cookies im Webhook-Request vom Zielsystem angenommen und verwendet. Dies ist vor allem relevant, um Sitzungen (Sessions) über den Webhook-Aufruf hinweg aufrechtzuerhalten. Datenschutzrechtlich ist zu prüfen, ob hierauf in den Datenschutzbestimmungen gesondert hingewiesen werden muss. Mehr zum Thema Datenschutz ist in diesem Artikel beschrieben.

• Authentifizierung: Hier wird zwischen Keine Authentifizierung (Sicherheit erfolgt z. B. über API-Key im Header) und Basic Auth (Abfrage von Benutzername und Passwort) gewählt.

Sicherheit und Schutz vor Missbrauch (Empfehlung)

1. 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.
2. 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.

2.3 Webhook-Aktionen vor der Ausführung

Optional können Aktionen aktiviert werden, die unmittelbar vor dem Absenden des Webhooks ausgeführt werden:

• User Message History: Fügt den bisherigen Nachrichtenverlauf der Unterhaltung zum Kontext hinzu. Dies ist nützlich, wenn das Zielsystem (z. B. ein CRM) den gesamten Gesprächskontext für die weitere Bearbeitung benötigt.

• Save File URL(s): Speichert die URLs von Dateien, die Nutzer:innen zuvor im Chat hochgeladen haben, im Kontext. Dies ist essenziell für Prozesse, bei denen Dokumente oder Bilder an ein Backend übertragen werden sollen.

3. Verwendung im Chatbot

Nachdem ein Webhook konfiguriert wurde, kann er an verschiedenen Stellen im Chatbot eingesetzt werden.

3.1 Webhooks als KI-Aktion

KI-Aktionen ermöglichen es dem KI-Agenten, bei Bedarf selbstständig eine Abfrage zu starten.

1. Unter Knowledge Base → RAG → in der Actions & Follow-Up Karte Add Action + wird eine neue Aktion erstellt.
2. Die Verknüpfung erfolgt über die Auswahl des zuvor erstellten Webhooks unter Tool auswählen.
3. Durch präzise Parameter-Beschreibungen weiß der KI-Agent, welche Informationen (z. B. eine ID) er vorab erfragen muss.

Mehr Informationen zu KI-Aktionen sind in diesem Artikel zu finden.

3.2 Webhooks in Formularen

In Formularen erfolgt die Integration an einer fest definierten Stelle im Abfragepfad.

1. Im Formular-Editor wird an der gewünschten Stelle auf das Plus-Symbol geklickt.
2. Aus der Element-Leiste wird Webhook ausgewählt.
3. Im erscheinenden Feld wird der gewünschte Webhook ausgewählt.

Mehr Informationen zu Formularen finden sich in diesem Artikel.

4. Testen und Validierung

Um die korrekte Funktion sicherzustellen, sollte jede Konfiguration geprüft werden.

1. Über den Button TESTEN oben rechts im Webhook-Editor wird die Test-Umgebung geöffnet.
2. Ein Formular zur Simulation der Datenbasis wird ausgewählt.

3. Mit TESTDATEN SENDEN wird die Anfrage ausgelöst und die Antwort der API validiert.
   

4. Zusätzlich Validierung der Funktion in der Preview (für Webhooks in Formularen) oder im KI Playground (für Webhooks in KI-Aktionen). Im KI Playground wird detailliert angezeigt, wie eine KI-Aktion ausgeführt wurde.

5. Praxisbeispiele

{
  "orderNumber": "{{order_number_input}}",
  "email": "{{email_input}}"
}

{{#if shopify_order_status_url}}

{{#if shopify_shopify_fulfillments}}

{{#if (eq shopify_status "pending")}}

Deine Bestellung ist bearbeitet, aber wurde noch nicht versandt.{{/if}}
{{#if (eq shopify_status "open")}}

Deine Bestellung wurde versandt.{{/if}}

{{#if (eq shopify_status "success")}}

Deine Bestellung wurde bestätigt.{{/if}}

{{#if (eq shopify_status "cancelled")}}

Deine Bestellung wurde storniert.{{/if}}

{{#if (eq shopify_status "error")}}

Es gab einen Fehler bei der Lieferung.{{/if}}

{{#if (eq shopify_status "failure")}}

Es ist etwas schief gelaufen bei der Lieferung.{{/if}}

{{else}}

Deine Bestellung wurde noch nicht versandt{{/if}}

{{else}}

Es gibt derzeit keine Bestellung für deine Angaben. Prüfe nochmals die Angaben oder schau auf der Bestellstatus-Seite nach:{{/if}}

{{#if order_status_response.tracking_url}}Sendung verfolgen{{else}}Zum Kundenkonto{{/if}}

{{#if order_status_response.tracking_url}}{{order_status_response.tracking_url}}{{else}}https://ihrshop.de/login{{/if}}