Webhooks

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

CX-Webhooks sind den ES-Webhooks ähnlich, mit der Ausnahme, dass die Anfrage- und Antwortfelder zur Unterstützung von CX-Funktionen geändert wurden.

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.
  • Er muss POST-Anfragen mit einem JSON-WebhookRequest-Text verarbeiten.
  • Er muss auf WebhookRequest-Anfragen mit einem JSON-WebhookResponse-Text antworten.
  • 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-Agent berechtigt sind, Anfragen zu stellen. Dies wird beim Erstellen einer Webhook-Ressource konfiguriert. Dialogflow CX unterstützt die folgenden Authentifizierungsverfahren:

HTTPS-Zertifikatsüberprüfung

Dialogflow verwendet standardmäßig den Standard-Vertrauensspeicher von Google, um HTTPS-Zertifikate zu prüfen. Wenn Sie Zertifikate verwenden möchten, die vom Standard-Vertrauensspeicher 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.

Webhook-Anfrage

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

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

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).

Webhook-Ressource erstellen

Wenn ein Webhook-Dienst ausgeführt wird, müssen Sie in Ihrem Agent eine Webhook-Ressource mit Verbindungs- und Authentifizierungsinformationen erstellen. So erstellen Sie eine Webhook-Ressource:

Console

  1. Öffnen Sie die Dialogflow CX Console.
  2. Wählen Sie Ihr GCP-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.
  7. Geben Sie die Webhook-Daten ein.
  8. Klicken Sie auf Speichern.

API

Siehe die Methode create für den Typ Webhook.

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# Nicht verfügbar Nicht verfügbar
Go Nicht verfügbar 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

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

Cloud Functions verwenden

Dialogflow lässt sich in Cloud Functions 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, kann der Agent den Webhook ohne spezielle Konfiguration sicher aufrufen.

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

  1. Das Dienstkonto Dialogflow-Dienst-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 diesen 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 die Dialogflow-Dienst-Agent Dienstkonto im Projekt Ihrer Funktion.

Service Directory für den privaten Netzwerkzugriff verwenden

Dialogflow 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.
  2. Das Dienstkonto Dialogflow-Dienst-Agent mit der folgenden Adresse muss für Ihr Agent-Projekt vorhanden sein:
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Gewähren Sie dem Dienstkonto Dialogflow-Dienst-Agent die folgenden IAM-Rollen:
    • 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

    Screenshot: Service Directory-Webhook.

    API

    Weitere Informationen finden Sie im Feld serviceDirectory für den Typ Webhook.

    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# Nicht verfügbar Nicht verfügbar
    Go Nicht verfügbar 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

Identitätstokens für Dienste

Wenn Dialogflow einen Webhook aufruft, wird ein Google-Identitätstoken mit der Anfrage bereitgestellt. Jeder Webhook kann das Token optional mit Google-Clientbibliotheken oder Open-Source-Bibliotheken wie github.com/googleapis/google-auth-library-nodejs validieren. Sie können beispielsweise die email des ID-Tokens so prüfen:

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