Zum Hauptinhalt springen

Webhooks verwenden

Verfasst von Jochem van de Weerthof

Mit Webhook-Aktionen kann Ihr KI-Agent während eines Gesprächs externe Dienste aufrufen.

Fast jede Webhook-Aktion lässt sich einem von zwei Anwendungsfällen zuordnen:

  1. Lesen – Daten abrufen

  2. Schreiben – Daten schreiben

Wenn Sie Ihre Einrichtung von Anfang an nach diesen zwei Anwendungsfällen ausrichten, lässt sich Ihr Agent leichter konfigurieren, testen und vertrauenswürdig einsetzen.

Bevor Sie beginnen

Stellen Sie sicher, dass Sie Folgendes haben:

  • Zugriff auf die Webhook-Funktion in Ihrem Abonnement

  • Einen funktionierenden API-Endpunkt

  • Authentifizierungsdaten (z. B. API-Schlüssel oder Bearer-Token)

  • Eine kurze Liste der Felder, die Ihre API benötigt

Dann: Öffnen Sie Ihren Agenten → Tools → aktivieren Sie Webhook → Aktion hinzufügen.

Anwendungsfall 1: Daten lesen

Verwenden Sie eine Lese-Aktion, wenn der Agent Informationen benötigt, bevor er antworten kann.

Typische Szenarien

  • Bestellstatus prüfen

  • Kundendaten abrufen

  • Konto- oder Buchungsinformationen validieren

Beispiel: Bestellstatus abrufen

Aktionseinrichtung

Feld

Wert

Titel

Bestellstatus abrufen

HTTP-Methode

GET

URL

https://api.demo-shop.com/v1/orders/status

Beschreibung

Ruft den aktuellen Versand- und Lieferstatus für eine bestimmte Bestellung ab

Wann verwenden

Verwenden, wenn ein Kunde nach dem Verbleib seiner Bestellung fragt oder die Lieferzeit wissen möchte

Inhaltstyp

none

Authentifizierungstyp

header

Authentifizierungsfeld

Schlüssel

Wert

Authorization

Bearer demo_read_token_123

Parameter

Name

Ort

Typ

Erforderlich

Beispiel

orderId

query

string

ja

ORD-10458

Vom Webhook gesendete Anfrage

GET /v1/orders/status?orderId=ORD-10458 HTTP/1.1
Host: api.demo-shop.com
Authorization: Bearer demo_read_token_123

Beispielantwort

{
  "orderId": "ORD-10458",
  "status": "shipped",
  "estimatedDeliveryDate": "2026-09-05",
  "carrier": "DHL",
  "trackingNumber": "DHL-77890012"
}

Anwendungsfall 2: Daten schreiben

Verwenden Sie eine Schreib-Aktion, wenn der Agent Daten in einem anderen System erstellen, aktualisieren oder abschließen soll.

Typische Szenarien

  • Support-Ticket erstellen

  • Kundenkontaktdaten aktualisieren

  • Termin stornieren oder verschieben

Beispiel: Support-Ticket erstellen

Aktionseinrichtung

Feld

Wert

Titel

Support-Ticket erstellen

HTTP-Methode

POST

URL

https://api.demo-helpdesk.com/v1/tickets

Beschreibung

Erstellt ein neues Support-Ticket im Helpdesk-System

Wann verwenden

Verwenden, wenn der Kunde ein Problem meldet, das nicht sofort gelöst werden kann, und der Erstellung eines Tickets zustimmt

Inhaltstyp

application/json

Authentifizierungstyp

header

Authentifizierungsfeld

Schlüssel

Wert

Authorization

Bearer demo_write_token_456

Parameter

Name

Ort

Typ

Erforderlich

Beispiel

ticket.subject

body

string

ja

Billing issue for invoice INV-983

ticket.description

body

string

ja

Customer says invoice amount is incorrect and requests review.

customer.email

body

string

nein

[email protected]

Vom Webhook gesendete Anfrage

POST /v1/tickets HTTP/1.1
Host: api.demo-helpdesk.com
Authorization: Bearer demo_write_token_456
Content-Type: application/json

{
  "ticket": {
    "subject": "Billing issue for invoice INV-983",
    "description": "Customer says invoice amount is incorrect and requests review."
  },
  "customer": {
    "email": "[email protected]"
  }
}

Beispielantwort

{
  "ticketId": "TCK-22091",
  "status": "open",
  "priority": "normal",
  "createdAt": "2026-09-02T10:14:22Z"
}

Eine Aktion pro Aufgabe

Kombinieren Sie Lese- und Schreibverhalten nicht in einer einzigen Aktion, es sei denn, Ihre API erfordert dies.

Best Practice: Eine Aktion zum Abrufen von Daten, eine separate Aktion zum Schreiben von Daten. Das reduziert Fehler und macht das Verhalten leichter überprüfbar.

Feldübersicht

Gilt für Lese- und Schreib-Aktionen gleichermaßen.

Aktionsfelder

Feld

Zweck

Titel

Nutzerfreundlicher Name

HTTP-Methode

GET, POST, PUT, PATCH oder DELETE

URL

Vollständige URL, einschließlich https://

Beschreibung

Was die Aktion tut

Wann verwenden

Genau, wann der Agent diese Aktion wählen soll

Tipp: Titel, Beschreibung und Wann verwenden sind die stärksten Signale, anhand derer der Agent die richtige Aktion auswählt — investieren Sie hier Zeit.

Eingabeparameter

Fügen Sie für jeden Wert, den Ihr Endpunkt erwartet, einen Parameter hinzu.

Feld

Hinweise

Name

Zu sendender Feldschlüssel. Unterstützt Punktnotation für verschachtelte Werte, z. B. ticket.name

Ort

query, header oder body

Typ

string, number, boolean, enum oder array

Erforderlich

Aktivieren für Pflichtfelder

Beschreibung

Erklären Sie den erwarteten Wert

Beispiel

Optional, hilft aber bei der Genauigkeit der Extraktion

Typspezifische Regeln

Typ

Regel

string

Optionale Mindestlänge/Maximale Länge

number

Optionaler Mindestwert/Höchstwert, mit Umschalter für Dezimalzahlen erlauben

enum

Muss mindestens einen zulässigen Enum-Wert enthalten

array

Elementtyp muss string, number oder boolean sein

Inhaltstyp

Wählen Sie eine Option:

  • application/json — wenn Ihr Endpunkt JSON erwartet

  • application/x-www-form-urlencoded

  • none

Authentifizierung

Wählen Sie, wo Auth-Felder gesendet werden: none, header, body oder query.

Wenn der Authentifizierungstyp header, body oder query ist, fügen Sie mindestens ein Schlüssel/Wert-Paar hinzu, zum Beispiel:

Schlüssel

Wert

Authorization

Bearer YOUR_TOKEN

Fehlerbehebung beim Speichern

Wenn das Speichern einer Aktion fehlschlägt, prüfen Sie folgende Bereiche:

Aktionsebene

  • Fehlender Titel

  • Ungültige Methode (muss GET, POST, PUT, PATCH oder DELETE sein)

  • Ungültige URL (muss eine vollständige URL sein)

  • Doppelter Aktionsname

Authentifizierung

  • Authentifizierungsfelder ohne Schlüssel oder Wert

Parameter

  • Ungültiger Ort (muss query, header oder body sein)

  • Ungültiger Typ

  • Enum-Parameter ohne zulässige Werte

  • Doppelter Parametername am selben Ort

  • Ungültige Mindestwert/Höchstwert-Einschränkungen (Mindestwert darf Höchstwert nicht überschreiten)

Sicherheit und Zuverlässigkeit

  • Verwenden Sie separate Anmeldedaten für Test und Produktion

  • Vergeben Sie API-Berechtigungen nach dem Prinzip der geringsten Rechte

  • Verwenden Sie immer HTTPS-Endpunkte, niemals reines HTTP

  • Bevorzugen Sie header-Authentifizierung gegenüber query-Authentifizierung, wenn möglich

  • Vermeiden Sie sensible Werte in Beispielen für Parameter

  • Gestalten Sie Schreib-Endpunkte nach Möglichkeit idempotent

  • Geben Sie klare API-Fehler von Ihrem externen System zurück

Anrufer verifizieren, bevor sensible Daten weitergegeben werden

Geben Sie niemals sensible Informationen allein aufgrund der Anrufer-ID weiter. Die Anrufer-ID lässt sich leicht fälschen und sollte nicht als Identitätsnachweis behandelt werden.

Verlangen Sie stattdessen die Art von Verifizierung, die auch ein menschlicher Mitarbeiter vor der Offenlegung von Kontodaten verwenden würde, zum Beispiel:

  • Letzte Ziffern der Kunden- oder Kontonummer

  • Geburtsdatum

  • Postleitzahl

  • Weitere wissensbasierte Angaben, die nur der echte Kunde kennen würde

Bauen Sie diese Prüfung direkt in die Aktion ein: Machen Sie die Verifizierungsfelder zu erforderlichen Parametern und legen Sie in „Wann verwenden" fest, dass der Agent diese Informationen abfragt und bestätigt, bevor er eine Aktion aufruft, die sensible Daten zurückgibt.

Hat dies deine Frage beantwortet?