Webhooks anwenden und konfigurieren

Die Abfrage des Bestellstatus gehört zu den häufigsten Service-Anliegen im E-Commerce. Da Anfragen wie „Wo bleibt meine Bestellung?" einen großen Teil des Support-Volumens ausmachen, lässt sich durch die Nutzung eines Webhooks zur Anbindung des Shopsystems eine fallabschließende Antwort generieren. Diese informiert Nutzer:innen ohne manuelles Eingreifen des Kundenservice über den aktuellen Stand der Bestellung bzw. Lieferung. Da Nutzer:innen die Begriffe „Bestellstatus" und „Sendungsverfolgung" oft synonym verwenden, deckt dieses Beispiel beide Bereiche ab. Der Webhook geht an das Shopsystem, ruft den aktuellen Bestell- und Sendungsstatus ab und der KI-Chatbot gibt die Information passend aus.

Was benötigt wird:

• 1x Formular zur Datenabfrage
• 1x Zugriff auf die API des Shopsystems (z. B. Shopify, Shopware)
• 1x Webhook für das Daten-Update zur Übermittlung des Bestellstatus; hat in diesem Beispiel den Kontextnamen order_status_response

1. Struktur des Abfrage-Prozesses

Um Informationen aus einem Shopsystem abzurufen, erfolgt die Identifikation der Bestellung in der Regel über zwei spezifische Angaben: die Bestellnummer und die E-Mail-Adresse. Der Prozess gliedert sich in folgende Schritte.

1. Abfrage der Bestellnummer: Erhebung der eindeutigen Identifikationsnummer der Bestellung. Validierung mittels RegExp (Regular Expression) optional.
2. Abfrage der E-Mail-Adresse: Zusätzliche Validierung zur Sicherstellung des Datenschutz-Standards inkl. E-Mail-Formatvalidierung.
3. Ausführung des Webhooks: Übermittlung der Daten an das Shopsystem.
4. Ausgabe der Antwort: Dynamische Erstellung der Nachricht basierend auf den vom System zurückgegebenen Werten.

2. Konfiguration des Webhooks

Für die Kommunikation mit dem Shopsystem wird im Bereich Integrationen → Webhooks (Push) ein neuer Webhook angelegt.

• URL: https://api.dein-shopsystem.de/v1/orders/{{orderId}}/status
• Methode: POST (oder GET, je nach API-Anforderung)
• Kontextname (Beispiel): order_status_response
• Headers:
  • X-Api-Key: <Dein-API-Key deines Shopsystems>
  • Content-Type: application/json
• Body (Beispiel) in JSON-Code:

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

3. Optional: Authentifizierung via Login (Alternative zur E-Mail-Abfrage)

Der Abfrage-Prozess kann durch eine automatische Identitätserkennung optimiert werden. Ist eine Person bereits im Kundenkonto eingeloggt, entfällt die manuelle Abfrage der E-Mail-Adresse. In diesem Fall ist lediglich die Eingabe der Bestellnummer erforderlich, um den Versandstatus abzurufen.

Formular-Gestaltung mit dem Conditional Switch

Die Steuerung, ob ein Login vorhanden ist oder nicht, erfolgt im Formular über das Element Conditional Switch.

1. Im Formular-Editor wird das Element Conditional Switch ausgewählt.
2. Über das 3-Punkte-Menü hinter einer Bedingung wird die Bearbeitungsmaske geöffnet.
3. In der Maske Bedingung bearbeiten werden der Variablenname, der Bedingungsoperator und der Vergleichswert definiert.
4. Mit Klick auf BEARBEITEN wird die Bedingung gespeichert.
5. Über das Plus-Symbol lassen sich weitere Verzweigungen hinzufügen, um verschiedene Login-Zustände abzubilden.

Folgende drei Bedingungen werden für eine präzise Steuerung empfohlen:

• jwt = logout: Dieser Status signalisiert, dass die Person zuvor eingeloggt war, die Sitzung jedoch beendet wurde. Hier erfolgt die Ausgabe eines Hinweistextes mit Verlinkung zum erneuten Login.
• jwt existiert: Die Person ist erfolgreich eingeloggt. Das Formular leitet unmittelbar zur Abfrage der Bestellnummer weiter.
• uniqueUserId existiert: Diese Bedingung dient als Fallback, falls keine Authentifizierung vorliegt. Die Person wird aufgefordert, sich einzuloggen.

Webhook-Konfiguration bei Login-Authentifizierung

Damit das Shopsystem erkennt, dass die Anfrage von einer bereits verifizierten Person stammt, muss das Sicherheitsticket (JWT) im Webhook mitgesendet werden.

Dies erfolgt in der Webhook-Gestaltung unter Headers anpassen (optional):

• Field: Authorization
• Value: Bearer

Zweck dieser Konfiguration: Durch diesen Header weist sich der KI-Chatbot gegenüber der API als autorisierter Vertreter der eingeloggten Person aus. Das System erkennt das Token und gibt die Bestelldaten frei, ohne dass eine zusätzliche E-Mail-Validierung im Chat-Verlauf notwendig ist.

4. Logik der Antwortnachricht (Handlebars)

Um auf verschiedene Rückgabewerte des Systems (z. B. „storniert", „in Bearbeitung", „versendet") zu reagieren, werden im Textblock des Formulars Handlebars-Vorlagen mit if-Verzweigungen eingesetzt. Dadurch werden technische Statusbezeichnungen in kundenfreundliche Texte übersetzt.

Beispiel eines Code-Schnipsels für die Status-Antwort:

{{#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}}

5. Dynamische Buttons und Fallbacks

Zusätzlich zum Textblock können Buttons genutzt werden, die ihr Verhalten basierend auf dem Webhook-Ergebnis ändern. Dies ist besonders nützlich, um direkt zur Sendungsverfolgung des Versanddienstleisters (z. B. DHL) zu verlinken.

• Bedingter Button-Text: Der Button zeigt „Versandstatus anzeigen" nur dann, wenn ein Paket verschickt wurde. Andernfalls erscheint ein allgemeiner Text wie „Bestellstatus".

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

• Bedingte Button-URL: Die Verlinkung führt entweder direkt zur Tracking-URL oder als Fallback auf eine allgemeine FAQ-Seite oder das Kundenkonto.

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

Diese Logik stellt sicher, dass Nutzer:innen stets ein hilfreiches nächstes Ziel angeboten bekommen (Fallback auf das Kundenkonto oder FAQ), falls noch keine Sendungsnummer vorliegt.

Die Umsetzung solcher Bedingungen in Buttons erfolgt über die Handlebars-Syntax innerhalb der Felder Button-Text und Button-URL.

6. Best Practice: Authentifizierung und Sicherheit

Als zusätzliche Sicherheitsprüfung kann die Bestellstatus-Abfrage an den Anmeldestatus der Nutzer:innen gekoppelt werden. Durch die Nutzung von Kontext-Informationen lässt sich prüfen, ob eine Person bereits eingeloggt ist.

• Präzise Validierung: Die Nutzung von RegExp für die Bestellnummer (z. B. Prüfung auf 11 Stellen und Startziffer "9") minimiert fehlerhafte API-Aufrufe und verbessert die Erfahrung der Nutzer:innen.

• Sicherheitsabfrage: Die Kombination aus Bestellnummer und E-Mail-Adresse dient als Legitimation.

Die Suche nach Seminaren oder Kursen gehört zu den Kernanliegen bei Bildungsanbietern oder Sporteinrichtungen. Um Nutzer:innen nicht nur statische Informationen, sondern Echtzeit-Verfügbarkeiten zu liefern, können, je nach technischer Infrastruktur, Daten entweder direkt aus einem Drittanbieter-system oder in einem zweistufigen Prozess (CSV-Suche + Webhook) ermittelt werden.

Was benötigt wird:

• 1x KI-Agent mit zugeordneter Wissensquelle (z. B. CSV-Datei für Kursdaten)
• 1x Webhook für die Live-Abfrage (z. B. Verfügbarkeit oder Wochenplan)
• 1x KI-Aktion zur Verknüpfung von Anfrage, Wissen und Webhook

Übersicht

1. Herangehensweise A: Zweistufige Suche (RAG + Webhook)
2. Herangehensweise B: Direkte Plan-Abfrage (Live-GET-Request)
3. Konfiguration der KI-Aktionen (AI Actions)
4. Entscheidungshilfe: Die passende Herangehensweise wählen
   
   

1. Herangehensweise A: Zweistufige Suche (CSV-Suche + Live-Check)

Dieses Szenario eignet sich, wenn Informationen über Kurse statisch in einer Datenbank (z. B. CSV-Datei) vorliegen, die aktuelle Belegung der Plätze jedoch dynamisch über eine API geprüft werden muss.

Der Prozess in zwei Schritten :

• Schritt 1 (Wissensabruf): Nutzer:innen suchen nach einem Thema (z. B. Plattdüütsch-Seminar). Der KI-Agent durchsucht die hinterlegte CSV-Datei in der Knowledge Base und findet passende Einträge inklusive einer technischen Kursnummer (SORT_NUMMER).
• Schritt 2 (Live-Check): Der KI-Agent nutzt die gefundene Kursnummer (SORT_NUMMER) automatisch als Variable für den Webhook-Aufruf, um bei der API die Anzahl freier Plätze anzufragen.

Technische Webhook-Konfiguration (Beispiel):

• URL: https://api.beispiel-anbieter.de/v1/verfuegbarkeit?seminarNo={{SORT_NUMMER}}
  • Die Variable {{SORT_NUMMER}} wird im Moment der Anfrage durch die Nummer aus der CSV-Datei ersetzt.
• Methode: GET
  
  

2. Herangehensweise B: Direkte Plan-Abfrage (Echtzeit-Wochenplan)

Diese Methode wird genutzt, wenn ein System bereits eine aktuelle Aufbereitung der Daten (z. B. einen Wochenplan) als Schnittstelle zur Verfügung stellt. Bei dieser Methode existiert keine Vorab-Suche in einer Datenbank oder Liste.

• Ablauf: Eine Anfrage wie „Welche Kurse gibt es heute?" triggert direkt die KI-Aktion. Diese nutzt einen Webhook, um live den aktuellen Plan vom Server abzurufen und im Chat auszugeben. Eine manuelle Suche in einer statischen CSV-Datei ist hierbei nicht notwendig, da das Backend des Anbieters die Daten in Echtzeit passend ausgeben kann.

Technische Webhook-Konfiguration:

• URL: https://sport-macht-spass.de/api/moin/wochenplan
• Methode: GET
  
  

3. Konfiguration der KI-Aktionen

Um Webhooks im Gesprächsfluss zu aktivieren, müssen diese als Werkzeug (Tool) innerhalb einer KI-Aktion hinterlegt werden. Mehr Informationen zu KI-Aktionen sind in diesem Artikel zu finden. 

1. Aktion anlegen: Unter Knowledge Base → RAG-Button → Add Action wird eine neue KI-Aktion erstellt.
2. Tool auswählen: Im Drop-down-Menü wird der zuvor angelegte Webhook (z. B. „Kurssuche" oder „Wochenplan") ausgewählt.
3. Instruktionen definieren: In den Feldern „Anweisungen vorher" und „Anweisungen danach" wird festgelegt, wie der KI-Agent die Nutzer:innen informieren soll (z. B. „Ich schaue kurz nach freien Plätzen...").

Zusätzliche Konfiguration für Herangehensweise A

Bei der Arbeit mit einer CSV-Datei (Herangehensweise A) sind zwei weitere Webhook-Konfigurationen notwendig:

4. Parameter hinterlegen: Damit der Agent die richtige Information aus der CSV an den Webhook übergeben kann, müssen Parameter definiert werden.

Beispielkonfiguration:

• Spaltenname in der CSV: SORT_NUMMER
• Parameter in der KI-Aktion: Es wird ein Parameter namens SORT_NUMMER (Typ: Zahl) angelegt.

      

• Dieser Parameter wird dann in die Webhook-URL aus der Webhook-Konfiguration und in der ausgegebenen Seminar-URL eingetragen: https://api.beispiel-anbieter.de/v1/verfuegbarkeit?seminarNo={{SORT_NUMMER}} & https://beispiel-unternehmen.de/seminare/{{SORT_NUMMER}}.

5. In den Instruktionen der KI-Aktion wird dem Agenten aufgetragen:
„Sofern du Seminare gefunden hast, führe immer eine Platzverfügbarkeitssuche durch". Der Agent nimmt dann den Wert aus der CSV-Spalte SORT_NUMMER des gefundenen „Plattdüütsch-Seminars" und setzt ihn in die Webhook-URL ein.

Eine detaillierte Anleitung zur allgemeinen Definition und Einrichtung von KI-Aktionen sowie zur Parameter-Steuerung findet sich in diesem Artikel.

4. Entscheidungshilfe: Die passende Herangehensweise wählen

Die Wahl zwischen einer direkten Abfrage und einer zweistufigen Suche hängt primär von der vorhandenen IT-Infrastruktur ab.

Vorteile der zweistufigen Suche (Herangehensweise A):

• Schutz der Schnittstelle (API): Durch die Vorab-Prüfung in der Knowledge Base (CSV-Datei) wird der Webhook nur ausgelöst, wenn eine gültige Entsprechung (z. B. eine ID oder ein Produkt) gefunden wurde. Dies verhindert fehlerhafte Anfragen an das Backend und schont die Server-Ressourcen.
• Nutzerkomfort durch Daten-Mapping: Nutzer:innen können in natürlicher Sprache suchen (z. B. nach einem Kursnamen). Die KI übernimmt im Hintergrund die Übersetzung in technische Parameter, die von der Datenbank benötigt werden. Es ist somit nicht erforderlich, dass Nutzer:innen komplizierte Artikelnummern oder IDs kennen.
• Präzise Fehlerbehandlung: Findet die KI in der Wissensquelle keinen Treffer, wird der Prozess vorzeitig gestoppt. Anstatt eine technische Fehlermeldung des Servers auszugeben, kann der Chatbot direkt eine verständliche Antwort liefern (z. B. „Dazu habe ich leider keinen passenden Eintrag gefunden").

Wann ist die Direkt-Abfrage (Herangehensweise B) sinnvoll?

Die direkte Abfrage ist dann empfehlenswert, wenn das System bereits optimierte Daten (wie tagesaktuelle Pläne) über eine Schnittstelle liefert und eine zusätzliche Filterung durch eine Liste nicht notwendig ist.

Die Übermittlung des Zählerstands ist ein klassischer Self-Service-Prozess bei Energieversorgern. Da hierbei vertragsrelevante Daten geändert werden, erfolgt die Umsetzung über ein zweistufiges Sicherheitsverfahren innerhalb eines einzigen Formulars. Als Schnittstelle nimmt der KI-Chatbot Daten entgegen, sendet diese zur Prüfung an das Backend und führt erst nach erfolgreicher Plausibilitätsprüfung die finale Änderung durch.

Was benötigt wird:

• 1x Formular zur Datenabfrage
• 5x Webhook
  • Authentifizierung: Abgleich der Kundendaten zur Identitätsprüfung
  • Zähler-Abfrage: Abruf des aktiven Zählers und des verbundenen Vertrages
  • Plausibilitätsprüfung: Technischer Check in der Datenbank des Energieversorgers, ob der eingegebene Wert realistisch ist
  • Zählerstandsmeldung (Standard): Übermittlung eines plausiblen Wertes
  • Zählerstandsmeldung (Abweichung): Übermittlung eines unplausiblen Wertes inklusive Begründung

Ablauf zusammengefasst

Phase 1: Identifikation und Legitimierung

Zunächst erfolgt die Abfrage der Kundennummer und des Geburtsdatums im Formular. Diese Daten werden über den ersten Webhook (Authentifizierung) an das Backend gesendet. Das System prüft die Übereinstimmung und schickt ein „Sicherheitsticket" (JWT) zurück, das im Kontext auth_response abgelegt wird.

Phase 2: Datenerfassung und Übermittlung

Nach erfolgreicher Prüfung fragt der KI-Chatbot den Zählerstand ab. Erst jetzt wird der zweite Webhook (Daten-Update) ausgelöst. Dieser „Brief" an das Unternehmen enthält nun sowohl den neuen Zählerstand als auch das Sicherheitsticket (auth_response), um die Anfrage zu autorisieren.

Phase 3: Abschluss und Rückmeldung

Das Unternehmen verarbeitet den Zählerstand und sendet eine Erfolgsmeldung zurück, die im Kontext customer_update_response gespeichert wird. Der KI-Chatbot nutzt diese Information, um den Nutzer:innen eine finale Bestätigung im Widge anzuzeigen.

 

1. Die Datenerhebung

Zunächst erfolgt die Abfrage der Kundennummer und des Geburtsdatums. Diese Felder sind im Formular mit Variablen verknüpft, die als Platzhalter fungieren. Das Geburtsdatum dient als Legitimation zur Änderung im Backend. Stimmt die Kundennummer nicht mit dem Geburtsdatum überein, wird der Vorgang abgebrochen und der Kunde darauf hingewiesen. Ist eine Übereinstimmung vorhanden, wird die Angabe in der Webhook-Handlebar-Variable (user_x in eckigen Klammern) gespeichert und der Vorgang fortgeführt. Im Formular sind die Eingabefelder mit den Variablen verknüpft, die wie leere Boxen funktionieren. Die Variablen-Namen werden in den geschweiften Klammern definiert.

• Variable 1: user_kundennummer
• Variable 2: user_geburtsdatum

 

2. Authentifizierung (erster Webhook)

Webhook 1: Authentifizierung

⚙️ Was passiert:	Der Chatbot prüft Kundennummer und Geburtsdatum.
🎯 Ziel:	Sicherstellen, dass die Person tatsächlich Kunde ist.
✅ Ergebnis:	Der Chatbot erhält das „Sicherheitsticket" (JWT) für den restlichen Prozess.

Sobald die Eingaben vorliegen, wird der erste Webhook ausgelöst, um die Berechtigung für Änderungen am Vertrag zu prüfen. In diesem Beispiel hat der Webhook den Kontextnamen auth_response. Sobald die Eingaben vorliegen, wird der erste Webhook ausgelöst, um die Berechtigung für Änderungen am Vertrag zu prüfen.

• Kontextname: auth_response
• URL: https://api.energieversorger.de/v1/customer/{{user_kundennummer}}/authenticate
• Methode: POST
• Body: Custom

{
  "customerNumber": "{{user_kundennummer}}",
  "birthDate": "{{user_geburtsdatum}}"
}

Was tatsächlich beim Auslösen passiert (Beispiel):

Geben Nutzer:innen die Nummer 12345 und das Datum 01.01.1980 ein, sieht der "Brief-Inhalt", den der Webhook an das System schickt, so aus:

{
  "customerNumber": "12345",
  "birthDate": "01.01.1980"
}

Die Antwort des Systems

Nach der Dateneingabe prüft der erste Webhook die Identität der Nutzer:innen gegen das Backend des Unternehmens. Der weitere Verlauf wird über ein Conditional Switch-Element gesteuert:

• Pfad A (Fehler): Schlägt der Abgleich fehl (z. B. falsche Kombination aus Kundennummer und Geburtsdatum), wird die Variable webhook_error gesetzt. Der KI-Chatbot gibt die Meldung wie „Authentifizierung nicht erfolgreich" aus. Um den Nutzer:innen eine weitere Chance zur korrekten Eingabe zu geben, wird das Formular an dieser Stelle nicht beendet, sondern mittels einer Verlinkung zurück zum Start der Datenerhebung geleitet (Neustart).
  
  

• Pfad B (Erfolg): Ist die Authentifizierung erfolgreich, wird das Sicherheitsticket im Kontext unter dem Kontextnamen auth_response gespeichert.

 

3. Abfrage des Zählerstands (zweiter Webhook)

Bevor ein Zählerstand gemeldet werden kann, muss der KI-Chatbot in Erfahrung bringen, welcher Zähler und welcher Vertrag den Nutzer:innen aktuell zugeordnet sind.

Webhook 2: Zählerabfrage (GET)

⚙️ Was passiert:	Der Chatbot fragt: „Welche Zähler gehören zu dieser Person?".
🎯 Ziel:	Erhalt des aktiven Zählers und des verbundenen Vertrages.
✅ Ergebnis:	Ein Datenpaket mit den spezifischen Zähler-Details (z. B. Zählernummer, Tarifart) im Hintergrund.

Zweck: In diesem Schritt erhält der Bot die Information, ob es sich um einen Ein- oder Zweitarifzähler (HT/NT) handelt. Dies ist die Voraussetzung, damit das Formular im nächsten Schritt die passenden Eingabefelder anzeigt.

Der Webhook wird folgendermaßen konfiguriert:

• Methode: GET
• URL: https://api.energieversorger-xyz.de/portal/app/meter-reading.
• Body-Option: Default (bei GET-Anfragen ist kein individueller Body notwendig).

Besonderheiten in der Authentifizierung: Anders als beim späteren Update benötigt dieser Webhook kein JWT im Header. Stattdessen werden zwei andere Sicherheitsmechanismen genutzt:

1. Verwendung von Cookies: Die Option Cookies verwenden ist aktiviert, um die bestehende Sitzung aus der Authentifizierung (Schritt 1) zu nutzen.
2. Basic Auth: Unter dem Punkt Authentifizierung sind der Benutzername und das entsprechende Passwort hinterlegt, um den Zugriff auf das Kundenportal zu autorisieren.

Ergebnis: Das System liefert ein großes Datenobjekt (JSON) mit Informationen zu allen Verträgen und Zählernummern zurück. Diese Daten dienen als Grundlage für den nächsten Schritt, der Zählerprüfung.

Das Formular zur Zählerprüfung und Tarif-Logik

Bevor ein Wert abgefragt wird, muss das System ermitteln, welche Art von Zähler vorliegt. Basierend auf dem Rückgabewert des Webhooks (check_ht_nt.code) verzweigt sich das Formular:

• Code 1 (Eintarif-Zähler): Es erfolgt eine einfache Abfrage des Zählerstands in kWh.
• Code 2 (Zweitarif-Zähler): Der KI-Chatbot fragt getrennt nach dem Haupttarif (HT) und dem Nebentarif (NT).

• Sperre: Falls das Backend meldet, dass für diesen Zähler aktuell keine Meldung möglich ist (z. B. intelligentes Messsystem), erfolgt ein Abbruch mit Verweis auf den telefonischen Kundenservice.

4. Zählerprüfung (dritter Webhook)

Webhook 3: Zählerprüfung

⚙️ Was passiert:	Der Bot prüft den Status des identifizierten Zählers.
🎯 Ziel:	Sicherstellen, dass der Zähler für manuelle Eingaben bereit ist.
✅ Ergebnis:	Entscheidung über den weiteren Prozessweg (Freigabe zur Eingabe oder Hinweis auf Sperre).

Dieser Webhook fungiert als „technischer Türsteher". Basierend auf der Antwort dieses Webhooks entscheidet ein Conditional Switch (basierend auf den Daten aus Webhook 2), ob die Nutzer:innen den Zählerstand eingeben dürfen (und wenn ja, welcher Pfad dann eingeschlagen wird) oder ob der Prozess gestoppt wird (z. B. wenn bereits ein Smart-Meter die Daten automatisch übermittelt).

• URL: beispiel-url-middleware.de/abcdefghijk123456789/vergleich
  • Hier wird die URL einer Middleware eingetragen, welche die Daten der Nutzer:innen mit den möglichen Zähler abgleicht (Hochtarifzähler, Niedrigtarifzähler und Hochtarifzähler, Gaszähler, Smartmeter etc.).
• Methode: POST
• Body (Beispiel): Custom

{
  "readings": "{{json webhook_zaehlerpruefung}}",
  "meter": "{{user_zaehlernummer}}"
}

 

5. Übermittlung und Plausibilitäts-Check (vierter & fünfter Webhook)

Die Nutzer:innen werden im Formular nun aufgefordert, den neuen Zählerstand anzugeben. Der Zählerstand direkt an das IT-System des Unternehmens gesendet, wo auch die Plausibilitätsprüfung stattfindet. Das System vergleicht den eingegebenen Wert mit historischen Daten (z. B. dem Vorjahresverbrauch). Das System prüft den Wert während der Übermittlung und gibt sofort eine Rückmeldung an den Chatbot zurück (z. B. impausible: true oder implausible:false).

• Was passiert: Der Bot sendet den Zählerstand zur Verbuchung an das System.
  • Der Logik-Check: Der Chatbot prüft über einen Conditional Switch das Feld response.unplausible.
• Ziel: Direkte Eintragung des Wertes in die Datenbank.
• Ergebnis: Das System antwortet, ob die Buchung erfolgreich war oder ob der Wert unplausibel ist.
  • Pfad A (Plausibel): Wenn das System "OK" meldet (implausible: false), erhält der Nutzer die Erfolgsmeldung. Der Verlauf endet mit dem vierten Webhook.
  • Pfad B (Unplausibel): Wenn das System meldet, dass der Wert unplausibel ist (z.B. extrem hoher Mehrverbrauch), leitet der Chatbot automatisch in die Korrekturschleife oder fragt nach einem Grund (z.B. Leerstand oder Zählerwechsel). Der fünfte Webhook kommt zum Einsatz.

Pfad A: plausible Eingabe (vierter Webhook)

Webhook 4: Zählerstand melden (Standard)

⚙️ Was passiert:	Wenn Webhook 3 sagt: „Alles ok (plausibel)", wird dieser Webhook ausgelöst.
✅ Ergebnis:	Der Wert wird direkt in die Datenbank des Unternehmens geschrieben.

Wird die Variable implausible vom Backend als "falsch" (false) gemeldet, wird der neue Zählerstand übermittelt und der Vorgang abgeschlossen.

Nachdem die Zählerstände erhoben und als plausibel eingestuft, erfolgt der eigentliche Zweck des Prozesses: die finale Übermittlung der Daten an das Backend. Das Sicherheitsticket aus der Authentifizierung wird im Header verwendet, um die Anfrage zu autorisieren.

• Header:
  • Field: Authorization
  • Value: Bearer {{auth_response.jwt}}
• Methode: POST
• Body (Beispiel):

{
  "customerNumber": "{{user_kundennummer}}",
  "updateType": "meterReading",
  "value": "{{user_zaehlerstand_neu}}"
}

Wenn die Nutzer:innen den Zählerstand eingeben, füllt der KI-Chatbot die Platzhalter automatisch aus dem Kontext (Gedächtnis) auf und schickt das fertige Datenpaket an das Unternehmen.

Wenn der Nutzer:innen nun den Zählerstand 4567 eingibt, füllt der Chatbot die Lücken automatisch aus dem Gedächtnis (Kontext) auf und schickt die fertigen Daten an das Backend.

Beispiel:

{
  "customerNumber": "12345",
  "updateType": "meterReading",
  "value": "4567"
}

 

Pfad B: Unplausible Eingabe (fünfter Webhook)

Webhook 5: Zählerstand melden (unplausibel)

⚙️ Was passiert:	Wenn Webhook 3 sagt: „Wert ist komisch", der Nutzer aber bestätigt: „Passt trotzdem", wird dieser genutzt.
🎯 Besonderheit:	Er sendet zusätzlich den Grund (z. B. Mehrverbrauch) und nutzt die Basic Auth („portal") sowie den X-COS_UA Header zur Identifikation.

Wird die Variable implausible vom Backend als „wahr" (true) gemeldet, erkennt der Chatbot eine starke Abweichung zum Vorjahresverbrauch und reagiert im Formular mit einem entsprechenden Hinweis über einen Conditional Switch (Bedingung: response.unplausible). Nutzer:innen erhalten daraufhin die Optionen: Eingabe korrigieren oder bestätigen.

1. Korrigieren: Die Nutzer:innen wählen diesen Pfad, wenn sie einen Tippfehler vermuten. Das Formular springt zurück zur Eingabe des Zählerstands.

2. Bestätigen: Nutzer:innen geben an, dass der Wert trotz Abweichung korrekt ist. In diesem Fall wird ein spezieller Webhook „Zählerstand melden (unplausibel)" ausgelöst (vierter Webhook). Hierfür muss über ein Multiple Choice-Element ein strukturierter Grund ausgewählt werden. Im Hintergrund werden technische Codes gespeichert, die eine automatisierte Archivierung in der Datenbank des Unternehmens ermöglichen.

• • Leerstand (Technischer Code: AB01)
  • Zählerwechsel (Technischer Code: AB02)
  • Mehrverbrauch (Technischer Code: AB03)
  • Vorherige Ablesung fehlerhaft (Technischer Code: AB04)

Nachdem die Zählerstände erhoben und als unplausibel begründet wurden, erfolgt die finale Übermittlung der Daten an das Backend mit den Infos aus dem Webhook 4 (enthält das Sicherheitsticket aus der Authentifizierung im Header für die Autorisierung der Anfrage).

Konfiguration des vierten Webhooks

• Kontextname: Zaehlerstandmeldung_unplausibel
• URL: https://workflow-beispiel.dein-server.de/webhook/a1b2-c3d4-beispiel-id
• Methode: POST
• Header:
  • Field: X-COS_UA
  • Value: MoinAI-Live
• Body: Custom

{
  "number": "{{check_ht_nt.first_number}}",
  "contracts": [
    {
      "number": "{{check_ht_nt.second_number}}",
      "meterReadingDetails": [
        {
          "meter": "{{check_ht_nt.meter}}",
          "equipment": "{{check_ht_nt.equipment}}",
          "register": "{{check_ht_nt.register}}",
          "resultNew": {
            "confirmed": "true",
            "explanationHint": "{{user_unplausible_reason}}",
            "result": "{{user_zaehlerstand}}",
            "readingdateBilling": "{{check_ht_nt.time}}"
          }
        }
      ]
    }
  ]
}

• Authentifizierung: BasicAuth Benutzername + Passwort

• Cookies verwenden: aktiviert

Best Practices für die Sicherheit

• Verschlüsselung: Durch die Nutzung von HTTPS wird sichergestellt, dass die Datenpakete auf dem Weg zum Server nicht von Unbefugten gelesen werden können.

• Zeitliche Begrenzung: Das JWT sorgt dafür, dass die Authentifizierung nur für die aktuelle Sitzung gültig bleibt.