Webhooks

Webhooks sind Dienste, die Ihre Geschäftslogik hosten oder andere Dienste aufrufen. Während einer Sitzung können Sie mit Webhooks die Daten verwenden, die Dialogflow CX per Natural Language Processing extrahiert hat, um dynamische Antworten zu generieren, erfasste Daten zu validieren oder Aktionen im Backend auszulösen.

Ein Webhook kann entweder ein Standard-Webhook oder ein flexibler Webhook sein. Bei einem Standard-Webhook werden die Anfrage- und Antwortfelder von Dialogflow CX definiert. Bei einem flexiblen Webhook definieren Sie die Anfrage- und Antwortfelder.

Sie können auch über den Anfrageparameter $request.webhook_status_code auf den HTTP-Statuscode des Webhook-Aufrufs zugreifen.

Standard-Webhooks

Bei Standard-Webhooks verwenden Sie von Dialogflow CX definierte Anfrage- und Antwortnachrichten. Die Anfragenachricht enthält viele Details zur Sitzung. Dazu gehören beispielsweise die aktuelle aktive Seite, die zuletzt übereinstimmende Intent, die Werte der Sitzungsparameter und die vom Agenten definierten Antworten.

Standard-Webhook-Anfrage

Wenn eine Auftragsausführung mit einem Webhook aufgerufen wird, sendet Dialogflow CX eine HTTPS-POST-Webhook-Anfrage an Ihren Webhook-Dienst. Der Text dieser Anfrage ist ein WebhookRequest-JSON-Objekt mit Informationen zur Sitzung.

Bei einigen Integrationen wird das Feld WebhookRequest.payload mit zusätzlichen Informationen gefüllt. Beispielsweise stellt die Dialogflow CX-Telefon-Gateway-Integration die Anrufer-ID des Endnutzers bereit.

Weitere Informationen finden Sie in der Referenzdokumentation zu WebhookRequest (V3) oder WebhookRequest (V3Beta1).

Standard-Webhook-Antwort

Nachdem Ihr Webhook-Dienst eine Anfrage erhalten hat, muss er eine Antwort senden, die die folgenden Anforderungen erfüllt:

• Die Antwort muss innerhalb des Zeitlimits erfolgen, das beim Erstellen der Webhook-Ressource konfiguriert wurde.
• Die Antwort darf maximal 64 KiB groß sein.

Weitere Informationen finden Sie in der Referenzdokumentation zu WebhookResponse (V3) oder WebhookResponse (V3Beta1).

Standardeinstellungen für Webhook-Ressourcen

In der folgenden Tabelle werden die Webhook-Ressourceneinstellungen für Standard-Webhooks beschrieben:

X	Element
Anzeigename	Der Name, der in der Console für den Webhook angezeigt wird.
Webhook-Zeitüberschreitung	Wenn Dialogflow CX eine HTTP-Anfrage an Ihren Webhook-Dienst sendet, steuert diese Einstellung das Zeitlimit in Sekunden für jeden einzelnen Anfrageversuch, nicht für den gesamten Konversationswechsel. Wenn bei einem Versuch eine Zeitüberschreitung auftritt oder ein vorübergehender Fehler auftritt, versucht Dialogflow CX es automatisch noch einmal. Dieser Wiederholungsversuch kann dazu führen, dass die Gesamtbearbeitungszeit bis zur Rückgabe eines Fehlers bis zu doppelt so lang ist wie der konfigurierte Zeitüberschreitungswert. Wenn nach dem Wiederholen eine Zeitüberschreitung auftritt, ruft Dialogflow CX ein webhook.error.timeout-Ereignis auf. Weitere Informationen finden Sie unter Automatische Wiederholungsversuche.
Typ	Legen Sie Service Directory fest, wenn Sie Service Directory für den Zugriff auf private Netzwerke verwenden. Legen Sie andernfalls Generischer Webdienst fest.
Webhook-URL	Geben Sie die URL-Adresse für Ihren Webhook-Dienst an.
Untertyp	Legen Sie Standard fest.
Umgebungsspezifischer Webhook	Sie können umgebungsspezifische Webhooks bereitstellen.
Authentifizierung	Weitere Informationen finden Sie im Abschnitt „Authentifizierung“.
Benutzerdefiniertes CA-Zertifikat	Damit werden benutzerdefinierte CA-Zertifikate hochgeladen.

Flexible Webhooks

Bei flexiblen Webhooks definieren Sie die HTTP-Methode der Anfrage, die URL-Parameter der Anfrage sowie die Felder der Anfrage- und Antwortnachrichten. In der Anfrage können nur ausgewählte Parameterwerte angegeben werden und die Antwort kann nur Parameterüberschreibungswerte enthalten. Dies vereinfacht die Schnittstelle zwischen dem Agenten und dem Webhook, da selten etwas anderes als Sitzungsparameterwerte kommuniziert werden muss. Außerdem wird die Webhook-Implementierung vereinfacht, da die Anfrage- und Antwortnachrichten nur die erforderlichen Informationen enthalten und Sie für verschiedene Szenarien eindeutige Webhook-Nachrichten bereitstellen können.

Flexible Webhook-Anfrage

Wenn Sie die Webhook-Ressource für Ihren Agenten erstellen, können Sie für Webhook-Anfragen Folgendes angeben:

• Die HTTP-Methode, die für Webhook-Anfragen verwendet wird, die an Ihren Webhook-Dienst gesendet werden.
• Sitzungsparameterwerte, die Dialogflow CX über die URL an Ihren Webhook-Dienst senden soll.
• Sitzungsparameterwerte, die Dialogflow CX über den JSON-Anfragetext an Ihren Webhook-Dienst senden soll, wenn Sie POST, PUT oder PATCH als Methode auswählen.

Wenn Sie Sitzungsparameterwerte über die Anfrage-URL oder den JSON-Text senden möchten, verwenden Sie Parameterreferenzen. Sie müssen die Parameterreferenz nicht URL-codieren oder in Anführungszeichen setzen. Zur Laufzeit maskiert Dialogflow CX den Parameterwert nach Bedarf. Eine Liste oder ein zusammengesetzter Wert wird als JSON bereitgestellt.

Wenn Sie eine Parameterreferenz im JSON-Text verwenden, müssen Sie die Referenz unabhängig vom Parametertyp in Anführungszeichen setzen. Wenn der Parameter tatsächlich ein numerischer Skalar, eine Liste oder ein zusammengesetzter Wert ist, entfernt Dialogflow CX die Anführungszeichen, wenn die Anfrage zur Laufzeit gesendet wird, um den Parameterdatentyp beizubehalten. String-Skalartypen bleiben in Anführungszeichen. Wenn ein numerischer Skalar, eine Liste oder ein zusammengesetzter Wert innerhalb eines Stringwerts referenziert wird (z. B. „Dies ist eine Zahl: $session.params.size“), wird der Parameter als String behandelt („Dies ist eine Zahl: 3“).

Sie können beispielsweise die Sitzungsparameterwerte fruit und size so in der Anfrage-URL angeben:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

Und im JSON-Anfragetext:

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

Flexible Webhook-Antwort

Wenn Sie die Webhook-Ressource für Ihren Agent erstellen, können Sie Sitzungsparameter angeben, die Dialogflow CX zur Laufzeit auf bestimmte Felder der Webhook-Antwort festlegen soll.

Ihre Antwort muss die folgenden Einschränkungen erfüllen:

• Die Antwort muss innerhalb des Zeitlimits erfolgen, das beim Erstellen der Webhook-Ressource konfiguriert wurde. Andernfalls kommt es zu einer Zeitüberschreitung der Anfrage.
• Die Antwort darf maximal 64 KiB groß sein.

Verwenden Sie das folgende Format, um ein Skalar-, Listen- oder zusammengesetztes Feld anzugeben:

$.fully.qualified.path.to.field

Betrachten Sie beispielsweise die folgende JSON-Antwort:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Verwenden Sie Folgendes, um das Feld „value“ anzugeben:

$.routes[0].legs[0].distance.value

Flexible Webhook-Ressourceneinstellungen

In der folgenden Tabelle werden die Webhook-Ressourceneinstellungen für flexible Webhooks beschrieben.

X	Element
Anzeigename	Der Name, der in der Console für den Webhook angezeigt wird.
Webhook-Zeitüberschreitung	Wenn Dialogflow CX eine HTTP-Anfrage an Ihren Webhook-Dienst sendet, steuert diese Einstellung das Zeitlimit in Sekunden für jeden einzelnen Anfrageversuch, nicht für den gesamten Konversationswechsel. Wenn bei einem Versuch eine Zeitüberschreitung auftritt oder ein vorübergehender Fehler auftritt, versucht Dialogflow CX es automatisch noch einmal. Dieser Wiederholungsversuch kann dazu führen, dass die Gesamtbearbeitungszeit bis zur Rückgabe eines Fehlers bis zu doppelt so lang ist wie der konfigurierte Zeitüberschreitungswert. Wenn nach dem Wiederholen eine Zeitüberschreitung auftritt, ruft Dialogflow CX ein webhook.error.timeout-Ereignis auf. Weitere Informationen finden Sie unter Automatische Wiederholungsversuche.
Typ	Legen Sie Service Directory fest, wenn Sie Service Directory für den Zugriff auf private Netzwerke verwenden. Legen Sie andernfalls Generischer Webdienst fest.
Webhook-URL	Geben Sie die URL-Adresse für Ihren Webhook-Dienst an. Diese kann Verweise auf Sitzungsparameter enthalten.
Untertyp	Legen Sie Flexibel fest.
Methode	Legen Sie die HTTP-Methode für die Webhook-Anfrage fest.
Anfragetext	Geben Sie den JSON-Anfragetext wie oben beschrieben an.
Antwortkonfiguration	Geben Sie die Sitzungsparameter an, die auf Antwortfelder festgelegt werden sollen, wie oben beschrieben.
Umgebungsspezifischer Webhook	Sie können umgebungsspezifische Webhooks bereitstellen.
Authentifizierung	Weitere Informationen finden Sie im Abschnitt zur Authentifizierung.
Benutzerdefiniertes CA-Zertifikat	Damit werden benutzerdefinierte CA-Zertifikate hochgeladen.

Vordefinierte benutzerdefinierte Vorlage verwenden

Dialogflow bietet vordefinierte benutzerdefinierte Vorlagen, mit denen Sie flexible Webhooks in Salesforce CRM einbinden können.

1. Rufen Sie den Tab Verwalten auf, wählen Sie Webhooks aus und klicken Sie dann auf Erstellen.
2. Wählen Sie unter Untertyp die Option Flexibel aus.
3. Klicken Sie auf Mit vordefinierter Vorlage konfigurieren.
4. Wählen Sie im Menü Integrationstyp die Option Salesforce aus.
5. Wählen Sie im Menü API-Name einen API-Namen aus. In der Vorlage wird das Webhook-Formular automatisch anhand des von Ihnen ausgewählten API-Namens ausgefüllt.
   1. Konfigurieren Sie die folgenden Felder manuell, falls zutreffend, basierend auf Ihren Parametern:
      • Webhook-URL
      • Methode
      • JSON-Anfragetext
      • Antwortkonfiguration
   2. Die erforderlichen OAuth-Felder werden im Abschnitt Authentifizierung hervorgehoben.
6. Klicken Sie auf Speichern.

Webhook-Dienstanforderungen

Ihr Webhook-Dienst muss die folgenden Anforderungen erfüllen:

• HTTPS-Anfragen verarbeiten HTTP wird nicht unterstützt. Wenn Sie Ihren Webhook-Dienst in Google Cloud mit einer Compute- oder serverlosen Computing-Lösung hosten, lesen Sie die Dokumentation zur Bereitstellung mit HTTPS. Weitere Hosting-Optionen finden Sie unter SSL-Zertifikat für Ihre Domain abrufen.
• Die URL des Webhook-Dienstes muss öffentlich zugänglich sein, es sei denn, sie wird als Cloud Run-Ressource gehostet oder als Service Directory-Webhook aufgerufen.
• Anfragen und Antworten werden wie im Abschnitt Standard-Webhook oder Flexibler Webhook beschrieben verarbeitet.
• Wenn Ihr Agent nicht in den Zugriff auf private Netzwerke von Service Directory eingebunden ist, befinden sich Webhook-Aufrufe außerhalb des Dienstperimeters und werden blockiert, wenn VPC Service Controls aktiviert ist. Service Directory unterstützt nur eine begrenzte Anzahl von Endpunkten. Weitere Informationen finden Sie unter Service Directory.

Authentifizierung

Sichern Sie Ihren Webhook-Dienst, damit nur Sie oder Ihr Dialogflow CX-Agent Anfragen stellen können. Konfigurieren Sie dies beim Erstellen oder Bearbeiten einer Webhook-Ressource. Dialogflow CX unterstützt die folgenden Authentifizierungsmechanismen:

X	Element
Authentifizierungsheader	In den Webhook-Einstellungen können Sie optionale HTTP-Header-Schlüssel/Wert-Paare angeben. Wenn angegeben, fügt Dialogflow CX diese HTTP-Header zu Webhook-Anfragen hinzu. Es ist üblich, ein einzelnes Paar mit dem Schlüssel authorization anzugeben. Die Headerwerte unterstützen Sitzungsparameterreferenzen und das Parsen von Systemfunktionen wie in statischen Antwortnachrichten. Wenn Sie für den Header authorization statische Anmeldedaten verwenden, empfehlen wir, die Anmeldedaten über Secret Manager bereitzustellen.
Basisauthentifizierung mit Nutzername und Passwort	Für Webhook-Einstellungen können Sie optionale Werte für den Nutzernamen und das Passwort für die Anmeldung angeben. Wenn angegeben, fügt Dialogflow CX Webhook-Anfragen einen Autorisierungs-HTTP-Header hinzu. Dieser Header hat das folgende Format: "authorization: Basic <base 64 encoding of the string username:password>". Wir empfehlen, Ihren Nutzernamen und Ihr Passwort über Secret Manager anzugeben.
OAuth von Drittanbietern	Sie können die OAuth-Konfiguration eines Drittanbieters angeben, damit Dialogflow CX ein Zugriffstoken aus dem OAuth-System austauscht und es dem HTTP-Header für die Autorisierung hinzufügt. Es wird nur der Clientanmeldedaten-Ablauf unterstützt. Wir empfehlen, den Clientschlüssel über Secret Manager bereitzustellen.
Zugriffstokens für Dienst-Agents	Eingestellt.
Dienstkonto	Sie können ein Dienstkonto für die Authentifizierung verwenden. Damit können Sie auf andere Google Cloud APIs zugreifen.
Dienst-Agent-ID-Tokens	Sie können im Abschnitt „Dienst-Agent-Authentifizierung“ die Option „ID-Token“ auswählen, um das ID-Token des Dienst-Agents für die Authentifizierung zu verwenden. So können Sie auf Cloud Run-Ressourcen zugreifen.
Gegenseitige TLS-Authentifizierung	Weitere Informationen finden Sie in der Dokumentation zur gegenseitigen TLS-Authentifizierung.

Hinweis: Wenn mehrere Authentifizierungsoptionen aktiviert sind, haben Optionen mit höherer Priorität Vorrang. Die Prioritätsreihenfolge ist wie folgt: Authentifizierungsheader, Standardauthentifizierung, OAuth von Drittanbietern, Dienst-Agent-Authentifizierung.

Hinweis: Wir empfehlen nicht, IP-Bereiche zur Authentifizierung von Webhook-Anfragen zu verwenden. Wenn Sie die Quell-IP-Adresse der Anfrage verwenden möchten, um die Verbindung zu Ihrem Netzwerkperimeter zu ermöglichen, lassen Sie Anfragen aus den unter https://www.gstatic.com/ipranges/goog.json aufgeführten Bereichen zu und lehnen Sie Verbindungen aus den unter https://www.gstatic.com/ipranges/cloud.json aufgeführten Bereichen ab. Dies sind die Adressen von Google, die zum Bereitstellen von Arbeitslasten von Drittanbietern verwendet werden können. Dialogflow kann keine IP-Bereiche für Maschinen garantieren, die Webhook-Anfragen senden.

Hinweis: Nach dem 15. August 2025 enthalten exportierte Agenten keine Rohwert-Anmeldedaten mehr für Authentifizierungsheader, die Standardauthentifizierung mit Nutzername und Passwort oder OAuth von Drittanbietern.

OAuth von Drittanbietern

Dialogflow CX erfasst ein Zugriffstoken von einem Drittanbieter-OAuth-Anbieter und fügt es dem Autorisierungs-HTTP-Header hinzu, wenn Webhook-Anfragen gestellt werden.

In der folgenden Tabelle werden die Ressourceneinstellungen für OAuth von Drittanbietern beschrieben:

X	Element
Client-ID	Die Client-ID, die beim Anfordern eines OAuth-Tokens verwendet werden soll.
Clientschlüssel	Das Secret, das beim Anfordern eines OAuth-Tokens verwendet werden soll. Wir empfehlen, den Clientschlüssel über Secret Manager bereitzustellen.
OAuth-Endpunkt-URL	Die URL, die zum Anfordern eines OAuth-Tokens verwendet werden soll.
OAuth-Bereiche	Eine durch Kommas getrennte Liste von Bereichen, für die das OAuth-Token verwendet werden kann.

Anfragen, die an die OAuth-Endpunkt-URL gesendet werden, um ein Token zu erhalten, enthalten nicht die benutzerdefinierten Anfrageheader, die für die Webhook-Anfrage konfiguriert wurden. Sie können benutzerdefinierte Informationen als Parameter im Abfragestring der OAuth-Endpunkt-URL an den OAuth-Server übergeben.

Hinweis: OAuth-Tokens von Drittanbietern werden für Webhook-Anfragen mit derselben Client-ID, Endpunkt-URL und denselben Bereichen innerhalb desselben Dialogflow CX-Agenten wiederverwendet, solange die Anfrage auf demselben Dialogflow CX-Server erfolgt und das Token nicht abgelaufen ist. Um eine Hochverfügbarkeit zu erreichen, werden Agenten auf vielen einzelnen Servern bereitgestellt, die keine OAuth-Token-Caches gemeinsam nutzen. Wenn Sie eine Lösung bereitstellen, die OAuth-Tokens von Drittanbietern verwendet, sollten Sie einen API-Proxy implementieren, um die Anzahl der Anfragen zu verwalten, die Ihr Agent an Ihren OAuth-Drittanbieter senden kann.

ID-Token des Dienst-Agents

Dialogflow CX kann mithilfe des Dialogflow CX-Dienst-Agents ein ID-Token generieren. Dieses Token wird dem HTTP-Header „Authorization“ hinzugefügt, wenn Dialogflow CX einen Webhook aufruft.

Ein ID-Token kann für den Zugriff auf Cloud Run-Ressourcen verwendet werden, nachdem Sie die Rolle „Cloud Run-Aufrufer“ (roles/run.invoker) zugewiesen haben.

service-agent-project-number@gcp-sa-dialogflow.

Wenn sich die Cloud Run-Ressourcen im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzlichen IAM-Berechtigungen (Identity and Access Management), um sie aufzurufen.

Die Zielgruppe, die zum Generieren des ID-Tokens verwendet wird, ist die gesamte Webhook-URL, ausgenommen Suchparameter. Wenn Sie Cloud Run verwenden, muss diese URL von den Cloud Run-Zielgruppen unterstützt werden.

Wenn die Webhook-URL beispielsweise so lautet:

https://myproject.cloudfunctions.net/my-function/method1?query=value

Die folgende URL muss in benutzerdefinierten Zielgruppen enthalten sein:

https://myproject.cloudfunctions.net/my-function/method1

Jeder Webhook kann das Token optional auch mit Google-Clientbibliotheken oder Open-Source-Bibliotheken wie der Google Auth-Bibliothek für Node.js validieren.

Wenn Ihr Webhook in Cloud Run gehostet wird und über einen Load Balancer aufgerufen wird, fügen Sie die URL Ihres Load Balancers als benutzerdefinierte Zielgruppe zu Cloud Run hinzu. Weitere Informationen zu benutzerdefinierten Zielgruppen finden Sie unter Benutzerdefinierte Zielgruppen für Dienste festlegen.

Dienstkonto

Dienstkonten können verwendet werden, um Webhook-Anfragen an alle Google APIs zu authentifizieren, die sie unterstützen.

Erstellen Sie ein Dienstkonto, falls noch nicht geschehen.

Da es sich bei Dienstkonten um Hauptkonten handelt, können sie auf Ressourcen in Ihrem Projekt zugreifen, indem Sie ihnen wie jedem anderen Hauptkonto eine Rolle zuweisen. Die E-Mail-Adresse des Dienstkontos wird verwendet, um ein Zugriffstoken zu generieren, das im Authorization-Header der Webhook-Anfrage gesendet wird.

Wenn Sie den Webhook für die Verwendung von Dienstkonten konfigurieren möchten, benötigen Sie die folgenden Berechtigungen:

• roles/iam.serviceAccountUser

Zum Generieren von Tokens benötigt der Dialogflow-Dienst-Agent die folgenden Berechtigungen:

• roles/iam.serviceAccountTokenCreator

Das Dienstkonto muss außerdem Berechtigungen für den Zugriff auf den Dienst haben, der den Webhook hostet.

Hinweis: Wenn Sie Dienstkonten in mehreren Projekten verwenden möchten, müssen Sie dafür sorgen, dass Ihre Organisationsrichtlinie dies unterstützt. Beide Berechtigungen müssen im Projekt gewährt werden, das das Dienstkonto enthält.

Secret Manager-Authentifizierung

Wenn Sie Authentifizierungsheader, die Basisauthentifizierung mit Nutzername und Passwort oder OAuth von Drittanbietern verwenden, können Sie die Anmeldedaten mit Secret Manager als Secrets speichern. So authentifizieren Sie Ihren Webhook mit Secrets:

1. Erstellen Sie Ihr Secret, falls Sie noch keines haben.
2. Weisen Sie dem Dialogflow-Dienst-Agenten die Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das neue Secret zu.
3. Kopieren Sie Ihre Anmeldedaten in die Zwischenablage.
4. Fügen Sie Ihrem Secret eine neue Secret-Version hinzu und fügen Sie Ihre Anmeldedaten als Secret-Wert ein:
   • Wenn Sie Authentifizierungsheader verwenden, geben Sie Bearer <YOUR_CREDENTIAL> ein.
   • Wenn Sie die Basisauthentifizierung mit Nutzername und Passwort verwenden, geben Sie <YOUR_USERNAME>:<YOUR_PASSWORD> ein.
   • Lassen Sie am Ende alle Zeilenumbrüche weg.
5. Kopieren Sie den Namen der Secret-Version, die Sie hinzugefügt haben. Das Namensformat ist projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Öffnen Sie den Bildschirm zum Bearbeiten des Webhooks.
7. Konfigurieren Sie die Authentifizierungseinstellungen:
   • Wenn Sie Authentifizierungsheader verwenden, erstellen Sie einen neuen Anfrageheader für die Secret-Version. Geben Sie „Authorization“ in das Feld Schlüssel ein und fügen Sie den Namen der Secret-Version in das Feld Secret-Version ein.
   • Klicken Sie für die Basisauthentifizierung mit Nutzername und Passwort unter Basisauthentifizierung auf Secret-Version und fügen Sie den Namen der Secret-Version in das Feld Secret-Version ein.
   • Wenn Sie OAuth von Drittanbietern verwenden, klicken Sie unter OAuth von Drittanbietern auf Secret-Version und fügen Sie den Namen der Secret-Version in das Feld Secret-Version ein.
8. Klicken Sie auf Speichern.

Hinweis: Wir unterstützen nur globale Secret Manager-Secrets. Regionale Secrets werden nicht unterstützt.

HTTPS-Zertifikatsüberprüfung

Dialogflow CX verwendet standardmäßig den Standard-Trust Store von Google, um HTTPS-Zertifikate zu prüfen. Wenn Sie Zertifikate verwenden möchten, die vom Standard-Trust Store von Google nicht für Ihren HTTPS-Server erkannt werden, z. B. selbst signierte oder benutzerdefinierte Root-Zertifikate, lesen Sie die Informationen unter Benutzerdefinierte CA-Zertifikate.

Umgebungsspezifische Webhooks

Wenn Sie Umgebungen verwenden, um die Produktion von der Entwicklung zu trennen, können Sie Ihre Webhooks umgebungsspezifisch konfigurieren. Sie können für jede Webhook-Ressource umgebungsspezifische URL- und Authentifizierungseinstellungen angeben.

Mit dieser Konfiguration können Sie Ihre Webhook-Code-Updates sicher entwickeln und testen, bevor Sie sie in der Produktion bereitstellen.

Webhook-Ressourcen erstellen oder bearbeiten

Nachdem Sie einen Webhook-Dienst ausgeführt haben, erstellen Sie in Ihrem Agent eine Webhook-Ressource, die Verbindungs- und Authentifizierungsinformationen enthält. Sie können die Einstellungen für Webhook-Ressourcen jederzeit bearbeiten.

So erstellen oder bearbeiten Sie eine Webhook-Ressource:

Console

1. Öffnen Sie die Dialogflow CX-Konsole.
2. Rufen Sie Ihr Projekt auf.
3. Wählen Sie den Agent aus.
4. Klicke auf den Tab Verwalten.
5. Klicken Sie auf Webhooks.
6. Klicken Sie auf Erstellen oder wählen Sie einen vorhandenen Webhook aus, um ihn zu bearbeiten.
7. Konfigurieren Sie die Standardeinstellungen für Webhook-Ressourcen oder die flexiblen Einstellungen für Webhook-Ressourcen.
8. Klicken Sie auf Speichern.

API

Informationen zum Erstellen einer Webhook-Ressource finden Sie unter der Methode create für den Typ Webhook. Informationen zum Bearbeiten einer Webhook-Ressource (mit Ausnahme von umgebungsspezifischen Einstellungen) finden Sie in der Methode patch oder update für den Typ Webhook. Zur Webhook API-Referenz

Wählen Sie ein Protokoll und eine Version für die Webhook-Referenz aus:

Protokoll	V3	V3beta1
REST	Webhook-Ressource	Webhook-Ressource
RPC	Webhook-Schnittstelle	Webhook-Schnittstelle
C++	WebhooksClient	Nicht verfügbar
C#	WebhooksClient	Nicht verfügbar
Go	WebhooksClient	Nicht verfügbar
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Nicht verfügbar	Nicht verfügbar
Python	WebhooksClient	WebhooksClient
Ruby	Nicht verfügbar	Nicht verfügbar

Schließen

Informationen zum Bearbeiten der umgebungsspezifischen Einstellungen für einen Webhook finden Sie in der Methode patch oder update für den Typ Environment. Rufen Sie die Umgebung zur API-Referenz auf

Wählen Sie ein Protokoll und eine Version für die Umgebungsreferenz aus:

Protokoll	V3	V3beta1
REST	Umgebungsressource	Umgebungsressource
RPC	Umgebungsoberfläche	Umgebungsoberfläche
C++	EnvironmentsClient	Nicht verfügbar
C#	EnvironmentsClient	Nicht verfügbar
Go	EnvironmentsClient	Nicht verfügbar
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	Nicht verfügbar	Nicht verfügbar
Python	EnvironmentsClient	EnvironmentsClient
Ruby	Nicht verfügbar	Nicht verfügbar

Schließen

Webhook-Fehler

Wenn bei der Verarbeitung einer Webhook-Anfrage ein Fehler auftritt, sollte Ihr Webhook-Code einen der folgenden HTTP-Statuscodes zurückgeben:

• 400: Ungültige Anfrage
• 401: Fehlende Autorisierung
• 403: Verboten
• 404: Nicht gefunden
• 500: Serverfehler
• 503: Dienst nicht verfügbar

Dialogflow CX löst in den folgenden Fehlersituationen ein integriertes Ereignis für einen Webhook-Fehler oder eine Zeitüberschreitung aus und setzt die Verarbeitung wie gewohnt fort:

• Das Zeitlimit für die Antwort wurde überschritten.
• Ein Fehlerstatuscode wird empfangen.
• Die Antwort ist ungültig.
• Der Webhook-Dienst ist nicht verfügbar.

Wenn der Webhook-Dienstaufruf durch einen API-Aufruf zur Intent-Erkennung ausgelöst wurde, enthält das Feld queryResult.webhookStatuses in der Antwort zur Intent-Erkennung die Webhook-Statusinformationen.

Automatische Wiederholungsversuche

Dialogflow CX wiederholt Anfragen bei bestimmten Webhook-Fehlern automatisch, um die Robustheit zu verbessern. Automatische Wiederholungsversuche sind standardmäßig aktiviert und können nicht deaktiviert werden.

Dialogflow CX führt bei vorübergehenden Fehlern wie Zeitüberschreitungen bei Anfragen, unterbrochenen Netzwerkverbindungen und HTTP-Statuscodes im 5xx-Bereich (z. B. 500 Server fault oder 503 Service unavailable) einen einzelnen Wiederholungsversuch aus. Terminal-Client-Fehler wie der HTTP-Statuscode 404 Not found schlagen sofort ohne Wiederholungsversuch fehl.

Kumulative Latenz und Zeitlimitbudgetierung

Da Dialogflow CX vorübergehende Fehler einmal wiederholt, kann ein nicht reagierender Webhook-Endpunkt zu einer kumulativen Bearbeitungszeit von bis zu dem Doppelten des konfigurierten Zeitüberschreitungswerts führen, bevor Dialogflow CX einen Fehler zurückgibt. Bei der standardmäßigen Zeitüberschreitung von 5 Sekunden wird beispielsweise ein nicht reagierender Endpunkt nach 5 Sekunden beim ersten Versuch und nach weiteren 5 Sekunden beim Wiederholungsversuch beendet. Dies führt zu einer Gesamtlatenz von etwa 10 Sekunden, bevor Dialogflow CX Fehler-Handler wie einen webhook.error.timeout-Ereignis-Handler oder einen sys.no-match-default-Ereignis-Handler aufruft.

Wenn Ihre Architektur strenge Upstream-Latenzlimits hat (z. B. Telefonie- oder IVR-Systeme (Interactive Voice Response), die Anrufe nach einem Zeitlimit von 10 Sekunden beenden), sollten Sie beide Versuche einplanen, indem Sie das Webhook-Zeitlimit auf die Hälfte des zulässigen Zeitfensters festlegen (z. B. zwischen 2,5 und 4 Sekunden).

Best Practices für Wiederholungsversuche

So verarbeiten Sie Wiederholungsversuche in Ihrem Webhook-Dienst effektiv:

• Implementieren Sie Idempotenz oder Anfrage-Deduplizierung in Ihrer Webhook-Dienstlogik, um doppelte Anfragen sicher zu verarbeiten.
• Wenn der Webhook-Vorgang länger als das konfigurierte Zeitlimit dauert, geben Sie sofort eine HTTP-Statuscode-200 OK-Antwort mit einer Fallback-Nachricht zurück und verarbeiten Sie die Aufgabe mit langer Ausführungszeit asynchron.

Cloud Run verwenden

Achtung: In diesem Abschnitt wird beschrieben, wie Sie sichere Cloud Run-Ressourcen für Dialogflow CX-Webhooks verwenden. Es wird empfohlen, Ihre Ressourcen zu schützen. Wenn Sie sich mit einem URL-basierten Nutzernamen und Passwort oder HTTP-Headern authentifizieren, müssen Sie den nicht authentifizierten Zugriff auf Ihre Cloud Run-Ressource zulassen.

Dialogflow CX ist in Cloud Run eingebunden, sodass Sie einen sicheren, serverlosen Webhook erstellen können. Wenn Sie eine Cloud Run-Ressource erstellen, die sich im selben Projekt wie Ihr Agent befindet, wählen Sie Dienst-Agent-Authentifizierung und dann in der Authentifizierungskonfiguration ID-Token aus, damit Ihr Agent Ihren Webhook sicher aufrufen kann.

In den folgenden beiden Fällen müssen Sie diese Integration manuell einrichten:

1. Das Dienstkonto des Dialogflow CX-Dienst-Agents mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:

   service-agent-project-number@gcp-sa-dialogflow.

   Dieses spezielle Dienstkonto und der zugehörige Schlüssel werden normalerweise automatisch erstellt, wenn Sie den ersten Agent für ein Projekt erstellen. Wenn Ihr Agent vor dem 1. November 2020 erstellt wurde, können Sie die Erstellung dieses speziellen Dienstkontos auslösen:
   1. Erstellen Sie einen neuen Agent für das Projekt.
   2. Führen Sie den folgenden Befehl aus:

      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id

2. Wenn sich Ihre Webhook-Funktion in einem anderen Projekt als der Agent befindet, müssen Sie dem Dienstkonto Dialogflow CX-Dienst-Agent in Ihrem Cloud Run-Ressourcenprojekt die IAM-Rolle Cloud Run-Aufrufer oder Cloud Functions-Aufrufer zuweisen.

Wählen Sie als Nächstes im Abschnitt Authentifizierungskonfiguration die Option Dienst-Agent-Authentifizierung > ID-Token aus.

Containerisierte Webhooks und das Go-ezcx-Framework verwenden

Informationen zum Implementieren eines containerisierten Webhooks mit Go finden Sie im Go ezcx-Framework. Dieses Framework vereinfacht viele der Schritte, die zum Erstellen eines Webhooks erforderlich sind.

Cloud Run mit rein internem Traffic verwenden

Hinweis: Die Verwendung von Cloud Run außerhalb des VPC Service Controls-Perimeters des Dialogflow CX-Agentenprojekts für Webhooks wird nicht unterstützt.

Sie können Cloud Run-Ressourcen, die für die Annahme von internem Traffic aus VPC-Netzwerken (Virtual Private Cloud) im selben Projekt oder im selben VPC Service Controls-Perimeter konfiguriert sind, als Webhook verwenden, sofern sich der Agent im selben Projekt oder im selben VPC Service Controls-Perimeter befindet.

Service Directory für den privaten Netzwerkzugriff verwenden

Dialogflow CX ist in den Zugriff auf private Netzwerke von Service Directory eingebunden, sodass eine Verbindung zu Webhook-Zielen in Ihrem VPC-Netzwerk hergestellt werden kann. Dadurch bleibt der Traffic im Google Cloud Netzwerk und es werden IAM und VPC Service Controls erzwungen.

So richten Sie einen Webhook ein, der auf ein privates Netzwerk ausgerichtet ist:

1. Folgen Sie der Anleitung unter Konfiguration des privaten Netzwerks von Service Directory, um Ihr VPC-Netzwerk und den Service Directory-Endpunkt zu konfigurieren.

   Hinweis: Dialogflow CX speichert Service Directory-Informationen 90 Sekunden lang im Cache. Das bedeutet, dass es 90 Sekunden dauert, bis die Änderung wirksam wird, wenn Sie den Service Directory-Endpunkt aktualisieren.

2. Das Dienstkonto des Dialogflow CX-Dienst-Agents mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:

   service-agent-project-number@gcp-sa-dialogflow.

   Weisen Sie dem Dienstkonto Dialogflow CX-Dienst-Agent im Projekt, in dem sich Ihr Service Directory befindet, die folgenden Rollen zu:

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   Wenn sich Ihr Service Directory in einem anderen Projekt als Ihr Dialogflow CX-Agent befindet, müssen Sie dem Dialogflow CX-Dienst-Agent-Konto im Projekt, in dem Ihr Dialogflow CX-Agent gehostet wird, die Rolle servicedirectory.viewer zuweisen.

3. Geben Sie beim Erstellen des Webhooks den Service Directory-Dienst, die URL und alle optionalen Authentifizierungsinformationen an.

   Console

   

   API

   Weitere Informationen finden Sie im Feld serviceDirectory für den Typ Webhook. Zur Webhook API-Referenz

   Wählen Sie ein Protokoll und eine Version für die Webhook-Referenz aus:

   Protokoll	V3	V3beta1
   REST	Webhook-Ressource	Webhook-Ressource
   RPC	Webhook-Schnittstelle	Webhook-Schnittstelle
   C++	WebhooksClient	Nicht verfügbar
   C#	WebhooksClient	Nicht verfügbar
   Go	WebhooksClient	Nicht verfügbar
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	Nicht verfügbar	Nicht verfügbar
   Python	WebhooksClient	WebhooksClient
   Ruby	Nicht verfügbar	Nicht verfügbar

   Schließen

Zur Fehlerbehebung können Sie eine private Verfügbarkeitsdiagnose einrichten, um zu prüfen, ob Ihr Service Directory richtig konfiguriert ist.

Beispiele und Fehlerbehebung

Weitere Informationen finden Sie in der Anleitung zu Webhooks.