Webhooks

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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

Standard-Webhooks

Bei Standard-Webhooks verwenden Sie Anfrage- und Antwortnachrichten, die in Konversations-Agents (Dialogflow CX) definiert sind. Die Anfrage enthält viele Details zur Sitzung. Dazu gehören beispielsweise die aktuell aktive Seite, der zuletzt zugeordnete Intent, Sitzungsparameterwerte und vom Kundenservicemitarbeiter definierte Antworten.

Standard-Webhook-Anfrage

Wenn eine Auftragsausführung mit einem Webhook aufgerufen wird, sendet Conversational Agents (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 zusätzliche Informationen in das Feld WebhookRequest.payload eingefügt. Die Dialogflow CX Phone Gateway-Integration liefert beispielsweise die Anrufer-ID des Endnutzers.

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 Webhook-Ressourceneinstellungen für Standard-Webhooks beschrieben:

Flexible Webhooks

Mit flexiblen Webhooks definieren Sie die HTTP-Anfragemethode, die URL-Parameter der Anfrage sowie die Felder der Anfrage- und Antwortnachrichten. Die Anfrage kann nur ausgewählte Parameterwerte enthalten und die Antwort nur Parameterüberschreibungswerte. Diese Einschränkung ist eigentlich von Vorteil, da sie die Schnittstelle zwischen dem Kundenservicemitarbeiter und dem Webhook vereinfacht. In der Regel müssen zwischen einem Kundenservicemitarbeiter und einem Webhook nur Sitzungsparameterwerte ausgetauscht werden. Außerdem wird die Webhook-Implementierung vereinfacht, da die Anfrage- und Antwortnachrichten nur das enthalten, was Sie benötigen, und Sie für verschiedene Szenarien eindeutige Webhook-Nachrichten bereitstellen können.

Flexible Webhook-Anfrage

Wenn Sie die Webhook-Ressource für Ihren Kundenservicemitarbeiter 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 Konversations-Agents (Dialogflow CX) über die URL an Ihren Webhook-Dienst senden sollten.
• Wenn Sie POST, PUT oder PATCH als Methode auswählen, können Sie Werte für Sitzungsparameter angeben, die Conversational Agents (Dialogflow CX) über den JSON-Textkörper der Anfrage an Ihren Webhook-Dienst senden sollen.

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-entkommentieren und sie nicht in Anführungszeichen setzen. Zur Laufzeit wird der Parameterwert von Konversations-Agents (Dialogflow CX) nach Bedarf URL-entkommentiert. Eine Liste oder ein zusammengesetzter Wert wird als JSON bereitgestellt.

Wenn Sie im JSON-Textkörper eine Parameterreferenz 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 der Konversationsagent (Dialogflow CX) die Anführungszeichen beim Senden der Anfrage zur Laufzeit, um den Datentyp des Parameters beizubehalten. String-Skalartypen 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“).

So können Sie beispielsweise die Werte der Sitzungsparameter fruit und size in die Anfrage-URL einfügen:

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

Und so in den JSON-Anfragetext:

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

Flexible Webhook-Antwort

Beim Erstellen der Webhook-Ressource für Ihren Agenten können Sie Sitzungsparameter angeben, die Konversations-Agenten (Dialogflow CX) zur Laufzeit in bestimmten Feldern der Webhook-Antwort festlegen 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 Webhook-Ressourceneinstellungen

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

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 Untertyp die Option 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. Anhand des von Ihnen ausgewählten API-Namens wird das Webhook-Formular automatisch ausgefüllt.

   1. Sie können die folgenden Felder gegebenenfalls basierend auf Ihren Parametern manuell konfigurieren:

      • Webhook-URL
      • Methode
      • JSON-Anfragetext
      • 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 Computing-Lösung oder einer Lösung für serverloses Computing auf der Google Cloud Platform hosten, lesen Sie die Produktdokumentation zum Bereitstellen 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-Funktion gehostet oder es wird als Webhook für das Dienstverzeichnis darauf zugegriffen.
• 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 Konversations-Agent (Dialogflow CX) berechtigt sind, Anfragen zu stellen. Dies wird beim Erstellen oder Bearbeiten einer Webhook-Ressource konfiguriert. Conversational Agents (Dialogflow CX) unterstützen die folgenden Authentifizierungsmechanismen:

OAuth von Drittanbietern

Konversations-Agents (Dialogflow CX) können ein Zugriffstoken von einem Drittanbieter-OAuth-Anbieter abrufen und bei Webhook-Anfragen dem Autorisierungs-HTTP-Header hinzufügen.

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

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.

Zugriffstokens für Dienst-Agents

Dieser Authentifizierungstyp wird nicht mehr unterstützt. Wir empfehlen die Migration zu Dienstkonten. So migrieren Sie:

1. Öffnen Sie die Konsole.
2. Rufen Sie die Webhook-Einstellungen auf.
3. Prüfen Sie, ob für Ihren Webhook die Authentifizierung des Kundenservicemitarbeiters verwendet wird. Wenn Keine oder keine Optionen ausgewählt sind, sind Sie fertig. Andernfalls fahren Sie mit den Schritten fort.
4. Wählen Sie für die Authentifizierung des Kundenservicemitarbeiters die Option Keine aus.
5. Konfigurieren Sie Ihren Kundenservicemitarbeiter für die Verwendung von Dienstkonten.

Dienstkonto

Dienstkonten können verwendet werden, um Webhook-Anfragen an alle 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 ihnen Zugriff auf Ressourcen in Ihrem Projekt gewähren, indem Sie ihnen eine Rolle zuweisen, wie Sie es auch für jedes andere Hauptkonto tun würden. Anhand 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, benötigt die folgenden Berechtigungen:

• roles/iam.serviceAccountUser

Damit Konversations-Agents (Dialogflow CX) Tokens generieren können, 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, auf dem der Webhook gehostet wird.

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 mithilfe von Secrets:

1. Erstellen Sie ein Secret, falls Sie noch keines haben.
2. Weisen Sie dem Dialogflow-Dienst-Agent 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 Ihre Anmeldedaten als geheimen Wert ein.
   • Wenn Sie Authentifizierungs-Header verwenden, geben Sie Bearer <YOUR_CREDENTIAL> ein.
   • Wenn Sie die Basisauthentifizierung mit Nutzername und Passwort verwenden, geben Sie stattdessen <YOUR_USERNAME>:<YOUR_PASSWORD> ein.
   • Lassen Sie am Ende kein Zeilenumbruchzeichen aus.
5. Kopieren Sie den Namen der soeben hinzugefügten Secret-Version. Das Format des Namens ist projects/{project_id}/secrets/{secret_id}/versions/{version_id}".
6. Öffnen Sie den Bearbeitungsbildschirm für den Webhook und gehen Sie so vor:
   • Wenn Sie Authentifizierungsheader verwenden, erstellen Sie einen neuen Header für die Anfrage der Secret-Version. Geben Sie „Autorisierung“ als Schlüssel ein und fügen Sie den Namen der Secret-Version in das Eingabefeld Secret-Version ein.
   • Wenn Sie die Basisauthentifizierung 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.

HTTPS-Zertifikatsüberprüfung

Konversations-Agents (Dialogflow CX) verwenden 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 von Ihnen definierte Webhook-Ressource können Sie eindeutige URL- und Authentifizierungseinstellungen für jede Umgebung angeben, die Sie für den Bot definiert haben.

So können Sie Ihre Webhook-Codeupdates 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:

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 Conversational Agents (Dialogflow CX) einen Webhook-Fehler oder ein integriertes Zeilimitereignis 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

Konversations-Agents (Dialogflow CX) enthalten interne Mechanismen, die bei bestimmten Webhook-Fehlern automatisch einen neuen Versuch starten, um die Robustheit zu verbessern. Es wird nur bei nicht endgültigen Fehlern noch einmal versucht (z. B. bei Zeitüberschreitungen oder Verbindungsfehlern).

So verringern Sie die Wahrscheinlichkeit von doppelten Anrufen:

• Legen Sie längere Zeitüberschreitungsschwellen für Webhooks fest.
• Unterstütze die Idempotency in der Webhook-Logik oder dedupliziere.

Cloud Run Functions verwenden

Konversations-Agents (Dialogflow CX) lassen sich in Cloud Run-Funktionen einbinden, sodass Sie problemlos einen sicheren, serverlosen Webhook erstellen können. Wenn Sie eine Funktion erstellen, die sich im selben Projekt wie Ihr Agent befindet, müssen Sie in der Authentifizierungskonfiguration nur Service Agent Auth -> ID Token auswählen. Ihr Agent kann dann Ihren Webhook sicher aufrufen.

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

1. Das Dienstkonto Conversational Agents (Dialogflow CX) Service Agent mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   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 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 den Cloud Functions-Invoker IAM-Rolle an das Conversational Agents (Dialogflow CX) Service Agent-Dienstkonto im Projekt Ihrer Funktion zuweisen.
3. Wählen Sie im Abschnitt „Authentifizierungskonfiguration“ die Option Service Agent Auth -> ID Token aus.

Containerisierte Webhooks und das Go ezcx-Framework verwenden

Wenn Sie einen containerisierten Webhook mit Go implementieren möchten, lesen Sie den Artikel Go ezcx-Framework. Dieses Framework kann viele der Schritte beim Erstellen eines Webhooks vereinfachen.

Cloud Run Functions nur für internen Traffic verwenden

Cloud Run-Funktionen, die so eingerichtet sind, dass sie internen Traffic von VPC-Netzwerken im selben Projekt oder im selben VPC SC-Perimeter akzeptieren, können als Webhook verwendet werden, solange sich der Agent im selben Projekt oder im selben VPC SC-Perimeter befindet.

Service Directory für den privaten Netzwerkzugriff verwenden

Conversational Agents (Dialogflow CX) werden 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.

2. Das Dienstkonto Conversational Agents (Dialogflow CX) Service Agent mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:

   service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

   Weisen Sie dem Dienstkonto Conversational Agents (Dialogflow CX) Service Agent die folgenden IAM-Rollen zu:
   • servicedirectory.viewer des Service Directory-Projekts
   • servicedirectory.pscAuthorizedService des Netzwerkprojekts

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-Oberfläche	Webhook-Oberfläche
   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 Ihre Service Directory-Konfiguration korrekt ist.

Beispiele und Fehlerbehebung

Weitere Informationen finden Sie in der Anleitung für Webhooks.