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 Back-End 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.

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, der zuletzt abgeglichene Intent, Werte für Sitzungsparameter und vom Agent definierte 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 werden im Feld WebhookRequest.payload zusätzliche Informationen eingefügt. Die Dialogflow CX Phone Gateway-Integration stellt beispielsweise die Anrufer-ID des Endnutzers bereit.

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

Standard-Webhook-Antwort

Sobald Ihr Webhook-Dienst eine Webhook-Anfrage empfängt, muss er eine Webhook-Antwort senden. Für die Antwort gelten die folgenden Einschränkungen:

• Die Antwort muss innerhalb eines Zeitlimits auftreten, das Sie beim Erstellen der Webhook-Ressource konfigurieren. Andernfalls wird das Zeitlimit der Anfrage ausgelöst.
• 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

Im Folgenden werden die Einstellungen für Webhook-Ressourcen für Standard-Webhooks beschrieben:

Begriff	Definition
Anzeigename	Der Name, der in der Konsole für den Webhook angezeigt wird.
Webhook-Zeitlimit	Wenn Dialogflow CX eine Webhook-Anfrage an Ihren Webhook-Dienst sendet, kann es zu einem Zeitüberschreitungsfehler kommen, während auf eine Antwort gewartet wird. Mit dieser Einstellung wird das Zeitlimit in Sekunden festgelegt. Wenn ein Zeitlimit überschritten wird, ruft Dialogflow CX das webhook.error.timeout-Ereignis auf.
Typ	Legen Sie Service Directory fest, wenn Sie Service Directory für den privaten Netzwerkzugriff verwenden. Andernfalls legen Sie Allgemeiner Webdienst fest.
Webhook-URL	Geben Sie die URL-Adresse für Ihren Webhook-Dienst an.
Subtyp	Auf Standard festgelegt
Umgebungsspezifischer Webhook	Sie können umgebungsspezifische Webhooks angeben.
Authentifizierung	Weitere Informationen finden Sie im Abschnitt zur Authentifizierung.
Benutzerdefiniertes CA-Zertifikat	Damit können Sie benutzerdefinierte CA-Zertifikate hochladen.

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 in der Antwort nur Parameterüberschreibungswerte. Diese Einschränkung ist sogar von Vorteil, da sie die Schnittstelle zwischen dem Agent und dem Webhook vereinfacht. In der Regel müssen nur Sitzungsparameterwerte zwischen einem Agent und einem Webhook übertragen werden. Außerdem wird die Webhook-Implementierung vereinfacht, da die Anfrage- und Antwortnachrichten nur die benötigten 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 Agent erstellen, können Sie Folgendes für Webhook-Anfragen angeben:

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

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

Wenn Sie im JSON-Text auf einen Parameter verweisen, müssen Sie den Verweis in Anführungszeichen setzen, unabhängig vom Typ des Parameters. Wenn der Parameter tatsächlich ein numerischer Skalar, eine Liste oder ein zusammengesetzter Wert ist, entfernt Dialogflow CX die Anführungszeichen beim Senden der Anfrage zur Laufzeit, um den Datentyp des Parameters beizubehalten. Skalare Stringtypen bleiben in Anführungszeichen. Wenn in einem Stringwert auf einen numerischen Skalar, eine Liste oder einen zusammengesetzten Wert verwiesen wird (z. B. „Das ist eine Zahl: $session.params.size“), wird der Parameter als String behandelt („Das 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 so zum 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 von Dialogflow CX zur Laufzeit auf bestimmte Felder der Webhook-Antwort festgelegt werden sollen.

Für die Antwort gelten die folgenden Einschränkungen:

• Die Antwort muss innerhalb eines Zeitlimits auftreten, das Sie beim Erstellen der Webhook-Ressource konfigurieren. Andernfalls wird das Zeitlimit der Anfrage ausgelöst.
• 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 Einstellungen für Webhook-Ressourcen

Im Folgenden werden die Einstellungen für Webhook-Ressourcen für flexible Webhooks beschrieben:

Begriff	Definition
Anzeigename	Der Name, der in der Konsole für den Webhook angezeigt wird.
Webhook-Zeitlimit	Wenn Dialogflow CX eine Webhook-Anfrage an Ihren Webhook-Dienst sendet, kann es zu einem Zeitüberschreitungsfehler kommen, während auf eine Antwort gewartet wird. Mit dieser Einstellung wird das Zeitlimit in Sekunden festgelegt. Wenn ein Zeitlimit überschritten wird, ruft Dialogflow CX das webhook.error.timeout-Ereignis auf.
Typ	Legen Sie Service Directory fest, wenn Sie Service Directory für den privaten Netzwerkzugriff verwenden. Andernfalls legen Sie Allgemeiner Webdienst fest.
Webhook-URL	Geben Sie die URL-Adresse für Ihren Webhook-Dienst an. Sie kann Verweise auf Sitzungsparameter enthalten.
Subtyp	Auf Flexibel festgelegt
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 angeben.
Authentifizierung	Weitere Informationen finden Sie im Abschnitt zur Authentifizierung.
Benutzerdefiniertes CA-Zertifikat	Damit können Sie benutzerdefinierte CA-Zertifikate hochladen.

Vordefinierte benutzerdefinierte Vorlage verwenden

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

1. Klicken Sie auf dem Tab Verwalten auf Webhooks und dann auf + Erstellen.

2. Wählen Sie unter Subtype (Untertyp) die Option Flexible (Flexibel) aus.

3. Klicken Sie auf Mit vordefinierter Vorlage konfigurieren, um die Funktion zu aktivieren.

4. Wählen Sie im Drop-down-Menü Integrationstyp die Option Salesforce aus.

5. Wählen Sie im Drop-down-Menü API-Name einen API-Namen aus. Das Webhook-Formular wird in der Vorlage automatisch anhand des von Ihnen ausgewählten API-Namens ausgefüllt.

   1. Sie können die folgenden Felder bei Bedarf manuell konfigurieren:

      • Webhook-URL
      • Methode
      • JSON-Text der Anfrage
      • Antwortkonfiguration

   2. Die erforderlichen OAuth-Felder werden im Abschnitt Authentifizierung hervorgehoben.

6. Klicken Sie auf Speichern, um den Webhook zu erstellen.

Webhook-Dienstanforderungen

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

• Er muss HTTPS-Anfragen verarbeiten. HTTP wird nicht unterstützt. Wenn Sie Ihren Webhook-Dienst mit einer Compute- oder Serverless Computing-Lösung auf der Google Cloud Platform hosten, lesen Sie die Produktdokumentation zur Bereitstellung mit HTTPS. Informationen zu anderen Hostingoptionen finden Sie unter SSL-Zertifikat für eine Domain anfordern.
• Die URL für Anfragen muss öffentlich zugänglich sein, es sei denn, sie wird als Cloud Run-Ressource gehostet oder als Service Directory-Webhook aufgerufen.
• Er muss Anfragen und Antworten wie im Abschnitt Standard-Webhook oder Flexibler Webhook beschrieben verarbeiten.
• Wenn Ihr Agent nicht in den privaten Verzeichniszugriff von Service Directory eingebunden ist, werden Webhook-Aufrufe außerhalb des Dienstperimeters betrachtet und beim Aktivieren von VPC Service Controls blockiert. Eingeschränkte Endpunkte werden von Service Directory unterstützt. Weitere Informationen finden Sie unter Service Directory.

Authentifizierung

Es ist wichtig, den Webhook-Dienst so zu sichern, dass nur Sie oder Ihr Dialogflow CX-Agent berechtigt sind, Anfragen zu stellen. Dies wird beim Erstellen oder Bearbeiten einer Webhook-Ressource konfiguriert. Dialogflow CX unterstützt die folgenden Authentifizierungsverfahren:

Begriff	Definition
Authentifizierungs-Header	Für Webhook-Einstellungen können Sie optionale HTTP-Header-Schlüssel/Wert-Paare angeben. Wenn diese angegeben werden, fügt Dialogflow CX diese HTTP-Header Webhook-Anfragen hinzu. Es ist üblich, ein einzelnes Paar mit dem Schlüssel authorization anzugeben. Die Headerwerte unterstützen Sitzungsparameterreferenzen und Parsing von Systemfunktionen wie in statischen Antwortnachrichten. Wenn Sie eine statische Anmeldedaten für den authorization-Header verwenden, empfehlen wir, die Anmeldedaten über Secret Manager bereitzustellen.
Basisauthentifizierung mit Nutzername und Passwort	Für die Webhook-Einstellungen können Sie optional Werte für den Anmeldenamen und das Passwort angeben. Wenn angegeben, fügt Dialogflow CX Webhook-Anfragen einen Autorisierungs-HTTP-Header hinzu. Dieser Header hat das Format "authorization: Basic <base 64 encoding of the string username:password>". Wir empfehlen, Nutzername und Passwort über Secret Manager anzugeben.
OAuth von Drittanbietern	Sie können die OAuth-Konfiguration von Drittanbietern so festlegen, dass Dialogflow CX ein Zugriffstoken vom OAuth-System abruft und es in den HTTP-Autorisierungsheader einfügt. Es wird nur der Ablauf der Clientanmeldedaten unterstützt. Wir empfehlen, das Client-Secret über Secret Manager bereitzustellen.
Zugriffstokens für Dienst-Agents	Nicht mehr unterstützt
Dienstkonto	Sie können ein Dienstkonto zur Authentifizierung verwenden. Damit kann auf andere Google Cloud APIs zugegriffen werden.
ID-Tokens für Dienst-Agents	Sie können in der Dienst-Agent-Authentifizierung die Option „ID-Token“ auswählen, um Dienst-Agent-ID-Tokens für die Authentifizierung zu verwenden. Damit kann auf Cloud Run-Ressourcen zugegriffen werden.
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. Prioritätsreihenfolge der Authentifizierungsoptionen: Authentifizierungsheader, Basisauthentifizierung, OAuth von Drittanbietern, Authentifizierung über Service-Agent.

Hinweis :Wir empfehlen nicht, IP-Bereiche zur Authentifizierung von Webhook-Anfragen zu verwenden. Wenn Sie die Quell-IP der Anfrage verwenden, um die Verbindung zu Ihrem Netzwerkperimeter zu ermöglichen, müssen Sie Anfragen aus den Bereichen, die unter https://www.gstatic.com/ipranges/goog.json aufgeführt sind, zulassen und dann alle Verbindungen aus den Bereichen, die unter https://www.gstatic.com/ipranges/cloud.json aufgeführt sind (die Google-Adressen, die zum Bereitstellen von Drittanbieterarbeitslasten verwendet werden können), ablehnen. Darüber hinaus kann Dialogflow keine Garantien für IP-Bereiche für Maschinen geben, die Webhook-Anfragen senden.

Hinweis: Nach dem 15. August 2025 enthalten exportierte Agents keine Anmeldedaten für Rohwerte mehr für Authentifizierungsheader, die einfache Authentifizierung mit Nutzername und Passwort sowie OAuth von Drittanbietern.

OAuth von Drittanbietern

Dialogflow CX kann ein Zugriffstoken von einem Drittanbieter-OAuth-Anbieter abrufen und es beim Senden von Webhook-Anfragen dem HTTP-Autorisierungsheader hinzufügen.

Im Folgenden werden die Ressourceneinstellungen für OAuth von Drittanbietern beschrieben:

Begriff	Definition
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, das Client-Secret ü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-Agents wiederverwendet, sofern die Anfrage auf demselben Dialogflow CX-Server erfolgt und das Token nicht abgelaufen ist. Um eine hohe Verfügbarkeit zu erreichen, werden Agents auf vielen einzelnen Servern bereitgestellt, die keine OAuth-Token-Caches gemeinsam nutzen. Wenn Sie eine Lösung bereitstellen, in der OAuth-Tokens von Drittanbietern verwendet werden, sollten Sie sorgfältig prüfen, ob Sie einen API-Proxy implementieren, um die Anzahl der Anfragen zu verwalten, die Ihr Agent an Ihren Drittanbieter-OAuth-Anbieter senden kann.

Dienst-Agent-ID-Token

Dialogflow CX kann mit dem Dialogflow CX-Dienst-Agent ein ID-Token generieren.

Das Token wird dem HTTP-Header „Authorization“ hinzugefügt, wenn Dialogflow CX einen Webhook aufruft.

Mit einem ID-Token kann auf Cloud Run-Ressourcen zugegriffen werden, nachdem Sie die Berechtigungen der Aufruferrolle für

[e-mail]

Wenn sich die Cloud Run-Ressourcen im selben Ressourcenprojekt befinden, benötigen Sie keine zusätzliche IAM-Berechtigung, um sie aufzurufen.

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

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 mit Google-Clientbibliotheken oder Open-Source-Bibliotheken wie github.com/googleapis/google-auth-library-nodejs validieren.

Dienstkonto

Dienstkonten können verwendet werden, um Webhook-Anfragen bei allen Google-APIs zu authentifizieren, die dies unterstützen.

Erstellen Sie ein Dienstkonto, falls noch nicht geschehen.

Da es sich bei Dienstkonten um Hauptkonten handelt, können Sie einem Dienstkonto Zugriff auf Ressourcen in Ihrem Projekt gewähren, indem Sie ihm eine Rolle zuweisen, wie Sie es auch für jedes andere Hauptkonto tun würden. Mit der E-Mail-Adresse des Dienstkontos wird ein Zugriffstoken generiert, das im Authorization-Header der Webhook-Anfrage gesendet wird.

Der Nutzer, der den Webhook für die Verwendung von Dienstkonten konfiguriert, muss die folgenden Berechtigungen haben:

• roles/iam.serviceAccountUser

Damit Dialogflow CX Tokens generieren kann, muss der Dialogflow-Dienst-Agent die folgenden Berechtigungen haben:

• 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, muss Ihre Organisationsrichtlinie dies unterstützen. Beide Berechtigungen müssen in dem Projekt erteilt 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 ein Secret, falls Sie noch keines haben.
2. Weisen Sie dem Dialogflow-Dienst-Agenten die Rolle Zugriffsperson für Secret Manager-Secret (roles/secretmanager.secretAccessor) für das neue Secret zu.
3. Kopieren Sie die Anmeldedaten in die Zwischenablage.
4. Fügen Sie Ihrem Secret eine neue Secret-Version hinzu. Fügen Sie die Anmeldedaten als Secret-Wert ein.
   • Wenn Sie Authentifizierungsheader verwenden, geben Sie Bearer <YOUR_CREDENTIAL> ein.
   • Wenn Sie die einfache Authentifizierung mit Nutzername und Passwort verwenden, geben Sie stattdessen <YOUR_USERNAME>:<YOUR_PASSWORD> ein.
   • Lassen Sie am Ende alle Zeilenumbruchzeichen weg.
5. Kopieren Sie den Namen der Secret-Version, die Sie gerade hinzugefügt haben. Das Namensformat ist projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
6. Öffnen Sie den Bearbeitungsbildschirm für Webhooks und gehen Sie dann so vor:
   • Wenn Sie Authentifizierungsheader verwenden, erstellen Sie einen neuen Secret-Versionsanfrageheader. Geben Sie „Authorization“ als Key ein und fügen Sie den Namen der Secret-Version in das Eingabefeld Secret version ein.
   • Wenn Sie die einfache Authentifizierung mit Nutzername und Passwort verwenden, klicken Sie unter Basisauthentifizierung auf Secret-Version und fügen Sie den Namen der Secret-Version in das Eingabefeld 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 Eingabefeld Secret-Version ein.
7. Klicken Sie auf Speichern.

Hinweis: Wir unterstützen nur den globalen Secret Manager. Die Verwendung regionaler Secrets wird 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 Produktionssysteme von Entwicklungssystemen zu isolieren (empfohlen), können Sie Ihre Webhooks umgebungsspezifisch konfigurieren. Für jede Webhook-Ressource, die Sie definieren, können Sie eindeutige URL- und Authentifizierungseinstellungen für jede Umgebung angeben, die Sie für den Agent definiert haben.

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

Webhook-Ressourcen erstellen oder bearbeiten

Wenn ein Webhook-Dienst ausgeführt wird, müssen Sie in Ihrem Agent eine Webhook-Ressource mit Verbindungs- und Authentifizierungsinformationen erstellen. Nach der Erstellung können Sie 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. Wählen Sie Ihr Google Cloud-Projekt aus.
3. Wählen Sie den Agent aus.
4. Wählen Sie den Tab Verwalten.
5. Klicken Sie auf Webhooks.
6. Klicken Sie auf Erstellen oder auf eine Webhook-Ressource in der Liste, um sie zu bearbeiten.
7. Geben Sie die Standardeinstellungen für Webhook-Ressourcen oder die flexiblen Einstellungen für Webhook-Ressourcen ein.
8. Klicken Sie auf Speichern.

API

Informationen zum Erstellen einer Webhook-Ressource finden Sie in der Methode create für den Typ Webhook. Informationen zum Bearbeiten einer Webhook-Ressource (mit Ausnahme umgebungsspezifischer Einstellungen) finden Sie in der patch- oder update-Methode 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	Umgebungsschnittstelle	Umgebungsschnittstelle
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 Ihr Webhook-Dienst bei der Verarbeitung einer Webhook-Anfrage einen Fehler feststellt, muss Ihr Webhook-Code einen der folgenden HTTP-Statuscodes zurückgeben:

• 400 Fehlerhafte Anfrage
• 401 Nicht autorisiert
• 403 Unzulässig
• 404 Nicht gefunden
• 500 Serverfehler
• 503 Dienst nicht verfügbar

In allen folgenden Fehlersituationen ruft Dialogflow CX einen Webhook-Fehler oder ein integriertes Zeitlimitereignis auf und fährt mit der Verarbeitung wie gewohnt fort:

• Antwortzeitlimit überschritten.
• Fehlerstatuscode 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 enthält interne Mechanismen, die bei bestimmten Webhook-Fehlern automatisch Wiederholungsversuche starten, um die Robustheit zu verbessern. Es werden nur nicht schwerwiegende Fehler wiederholt, z. B. Zeitüberschreitungs- oder Verbindungsfehler.

So verringern Sie die Wahrscheinlichkeit von doppelten Anrufen:

• Längere Zeitüberschreitungsschwellenwerte für Webhooks festlegen
• Unterstützen Sie die Idempotenz in der Webhook-Logik oder führen Sie eine Deduplizierung durch.

Cloud Run verwenden

Hinweis :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 jedoch mit URL-basiertem Nutzernamen und Passwort oder HTTP-Headern authentifizieren, sollten Sie nicht authentifizierten Zugriff auf Ihre Cloud Run-Ressource

zulassen.

Dialogflow CX lässt sich in Cloud Run einbinden, 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 in der Authentifizierungskonfiguration Service Agent Auth -> ID Token aus, damit Ihr Agent den Webhook sicher aufrufen kann.

Es gibt jedoch zwei Situationen, in denen Sie diese Integration manuell einrichten müssen:

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

   [e-mail]

   Dieses spezielle Dienstkonto und der zugehörige Schlüssel werden beim Erstellen des ersten Agents für ein Projekt normalerweise automatisch erstellt. Wenn Ihr Agent vor dem 1. November 2020 erstellt wurde, können Sie dieses spezielle Dienstkonto erstellen:
   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 die Webhook-Funktion in einem anderen Projekt als der Agent befindet, müssen Sie dem Dienstkonto Dialogflow CX-Dienst-Agent im Projekt Ihrer Cloud Run-Ressource die Cloud Run-Aufrufer- oder Cloud Functions-Aufrufer-IAM-Rolle zuweisen.
3. Wählen Sie im Abschnitt „Auth-Konfiguration“ die Option Service Agent Auth -> ID Token aus.

Containerisierte Webhooks und das Go-Framework „ezcx“ verwenden

Wenn Sie einen containerisierten Webhook mit Go implementieren möchten, sehen Sie sich das Go-EZCX-Framework an. Dieses Framework kann viele der Schritte vereinfachen, 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-Agent-Projekts für Webhooks wird nicht unterstützt.

Cloud Run-Ressourcen, die so eingerichtet sind, dass sie internen Traffic von VPC-Netzwerken im selben Projekt oder im selben VPC Service Controls-Perimeter akzeptieren, können als Webhook verwendet werden, 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 wird in privaten Service Directory-Zugriff eingebunden, sodass eine Verbindung zu Webhook-Zielen in Ihrem VPC-Netzwerk hergestellt werden kann. Dadurch wird der Traffic innerhalb des Google Cloud-Netzwerks beibehalten und IAM sowie VPC Service Controls erzwungen.

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

1. Folgen Sie der Anleitung unter Private Netzwerkkonfiguration für Service Directory, um Ihr VPC-Netzwerk und Ihren Service Directory-Endpunkt zu konfigurieren.

   Hinweis :Dialogflow CX speichert Service Directory-Informationen für 90 Sekunden im Cache. Wenn Sie den Service Directory-Endpunkt aktualisieren, dauert es also 90 Sekunden, bis die Änderung wirksam wird. Wenn Sie mehrere Endpunkte für die Redundanz einrichten, kann es außerdem sein, dass Dialogflow CX 90 Sekunden lang Traffic über einen fehlerhaften Endpunkt sendet.

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

   [e-mail]

   Weisen Sie dem Dienstkonto Dialogflow CX Service Agent in dem 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, außerdem die Rolle servicedirectory.viewer zuweisen.

3. Geben Sie beim Erstellen des Webhooks den Service Directory-Dienst mit der URL und 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

Anleitung für Webhooks