Webhooks

Webhooks sont des services qui hébergent votre logique métier ou appeler d'autres services. Pendant une session, les webhooks vous permettent d'utiliser Données extraites par le système de traitement du langage naturel de Dialogflow CX pour générer des réponses dynamiques, valider les données collectées ou déclencher des actions sur le backend.

Un webhook peut être un webhook standard ou un webhook flexible. Avec un webhook standard, les champs de requête et de réponse sont définis par Dialogflow. Avec un webhook flexible, vous définissez les champs de requête et de réponse.

Webhooks standards

Avec les webhooks standards, vous utilisez des messages de requête et de réponse définis par Dialogflow. Le message de requête fournit de nombreux détails sur la session. Par exemple, la page active en cours, l'intent mis en correspondance récent, les valeurs des paramètres de session et les réponses définies par l'agent sont toutes incluses.

Requête de webhook standard

Lorsqu'un fulfillment avec un webhook est appelé, Dialogflow envoie à votre service de webhook une requête de webhook POST HTTPS. Le corps de cette requête est un objet JSON WebhookRequest. avec des informations sur la session.

Un peu intégrations Remplissez le champ WebhookRequest.payload avec des informations supplémentaires. Par exemple, Intégration de la passerelle de téléphonie Dialogflow CX fournit le numéro de l'appelant de l'utilisateur final.

Pour en savoir plus, consultez la documentation de référence sur WebhookRequest(V3) ou WebhookRequest(V3Beta1).

Réponse webhook standard

Une fois que votre service webhook a reçu une requête de webhook, il doit envoyer une réponse de webhook. Les limites suivantes s'appliquent à votre réponse :

• La réponse doit se produire dans un délai d'expiration que vous configurez lors de la création de la ressource de webhook, sinon la requête expirera.
• La taille de la réponse doit être inférieure ou égale à 64 Kio.

Pour en savoir plus, consultez la documentation de référence sur WebhookResponse(V3) ou WebhookResponse(V3Beta1).

Paramètres de ressources de webhooks standards

Vous trouverez ci-dessous la description des paramètres de ressource webhook pour les webhooks standards :

Terme	Définition
Nom à afficher	Nom affiché dans la console pour le webhook.
Délai avant expiration du webhook	Lorsque Dialogflow envoie une requête de webhook à votre service de webhook, celle-ci peut expirer en attendant une réponse. Ce paramètre contrôle ce délai en secondes. En cas d'expiration du délai, Dialogflow appelle un événement webhook.error.timeout.
Type	Définissez ce paramètre sur Annuaire des services si vous utilisez l'annuaire des services pour l'accès à un réseau privé. Sinon, définissez-le sur Service Web générique.
URL du webhook	Indiquez l'adresse URL de votre service de webhook.
Sous-type	Définissez-le sur Standard.
Webhook spécifique à l'environnement	Vous pouvez fournir des webhooks spécifiques à l'environnement.
Authentification	Consultez la section sur l'authentification.
Certificat CA personnalisé	Ceci est utilisé pour importer des certificats CA personnalisés.

Webhooks flexibles

Avec les webhooks flexibles, vous définissez la méthode HTTP de la requête, les paramètres d'URL de la requête et les champs des messages de requête et de réponse. Seules certaines valeurs de paramètres sont fournies. et la réponse ne peut fournir que des valeurs de remplacement de paramètres. Cette limitation est en fait avantageuse, car cela simplifie l'interface entre l'agent et le webhook. Il est rarement nécessaire de communiquer autre chose que des valeurs de paramètre de session entre un agent et un webhook. Cela simplifie également l'implémentation de votre webhook, car les messages de requête et de réponse ne contiennent que ce dont vous avez besoin, et vous pouvez fournir des messages webhook uniques pour différents scénarios.

Requête de webhook flexible

Lors de la création de la ressource de webhook pour votre agent, vous pouvez spécifier les éléments suivants pour les requêtes webhook:

• Méthode HTTP utilisée pour les requêtes webhook envoyé au service de webhook.
• Valeurs des paramètres de session que Dialogflow doit envoyer à votre service de webhook à l'aide de l'URL.
• Si vous choisissez la méthode POST, PUT ou PATCH, vous pouvez spécifier les valeurs des paramètres de session que Dialogflow doit l'envoyer à votre service de webhook via le corps JSON de la requête.

Pour envoyer des valeurs de paramètre de session à l'aide de l'URL de requête ou du corps JSON, utilisez Références des paramètres comme vous le feriez normalement. Il n'est pas nécessaire d'échapper l'URL de la référence du paramètre. et que vous n'entourez pas la référence de guillemets. Au moment de l'exécution, Dialogflow effectue un échappement dans l'URL de la valeur du paramètre si nécessaire. Une liste ou une valeur composite est fournie au format JSON.

Lorsque vous utilisez une référence de paramètre dans le corps JSON, vous devez mettre la référence entre guillemets, quel que soit le type du paramètre. Si le paramètre est en fait une valeur scalaire, une liste ou une valeur composite numérique, Dialogflow supprime les guillemets lors de l'envoi de la requête au moment de l'exécution pour préserver le type de données du paramètre. Les types scalaires de chaîne resteront entre guillemets. Si une valeur numérique scalaire, de liste ou composite est référencée dans une valeur de chaîne (par exemple : "Il s'agit d'un nombre: $session.params.size"), le paramètre est traité comme une chaîne ("Voici un nombre: 3").

Par exemple : vous pouvez fournir les valeurs des paramètres de session fruit et size à l'URL de la requête, comme ceci:

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

Et, au corps JSON de la requête, comme ceci:

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

Réponse webhook flexible

Lors de la création de la ressource de webhook pour votre agent, vous pouvez spécifier des paramètres de session que Dialogflow doit définir à des champs spécifiques de la réponse webhook au moment de l'exécution.

Les limites suivantes s'appliquent à votre réponse :

• La réponse doit se produire dans un délai d'expiration que vous configurez lors de la création de la ressource de webhook, sinon la requête expirera.
• La taille de la réponse doit être inférieure ou égale à 64 Kio.

Utilisez le format suivant pour spécifier un champ scalaire, de liste ou composite:

$.fully.qualified.path.to.field

Par exemple : Prenons la réponse JSON suivante:

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

Pour spécifier la "valeur" , utilisez les éléments suivants:

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

Paramètres des ressources de webhook flexible

La section suivante décrit les paramètres de ressources de webhooks flexibles:

Terme	Définition
Nom à afficher	Nom affiché dans la console pour le webhook.
Délai avant expiration du webhook	Lorsque Dialogflow envoie une requête de webhook à votre service de webhook, celle-ci peut expirer en attendant une réponse. Ce paramètre contrôle ce délai en secondes. En cas de délai avant expiration, Dialogflow appelle un événement webhook.error.timeout.
Type	Définissez la valeur sur Annuaire des services si vous utilisez l'annuaire des services pour l'accès privé au réseau, sinon définissez la valeur sur Service Web générique.
URL du webhook	Indiquez l'adresse URL de votre service de webhook, qui peut inclure des références à des paramètres de session.
Sous-type	Définir sur Flexible
Méthode	Définissez la méthode HTTP pour la requête webhook.
Corps de la requête	Indiquez le corps JSON de la requête comme décrit ci-dessus.
Configuration de la réponse	Indiquez les paramètres de session qui doivent être définis dans les champs de réponse comme décrit ci-dessus.
Webhook spécifique à l'environnement	Vous pouvez fournir des webhooks spécifiques à l'environnement.
Authentification	Consultez la section sur l'authentification.
Certificat CA personnalisé	Ceci est utilisé pour importer des certificats CA personnalisés.

Utiliser un modèle personnalisé prédéfini

Dialogflow propose des modèles personnalisés prédéfinis que vous pouvez utiliser pour intégrer des webhooks flexibles au CRM Salesforce.

1. Dans l'onglet Gérer, cliquez sur Webhooks, puis sur + Créer.

2. Sous Sous-type, sélectionnez Flexible.

3. Cliquez sur Configurer à l'aide d'un modèle prédéfini pour activer cette fonctionnalité.

4. Dans le menu déroulant Type d'intégration, sélectionnez Salesforce.

5. Dans le menu déroulant Nom de l'API, sélectionnez un nom d'API. Le modèle remplit automatiquement le formulaire du webhook en fonction du nom de l'API que vous choisir.

   1. Le cas échéant, vous pouvez configurer manuellement les champs suivants, en fonction vos paramètres:

      • URL du webhook
      • Méthode
      • Corps de la requête JSON
      • Configuration de la réponse

   2. Les champs OAuth obligatoires sont mis en surbrillance dans la section Authentification. .

6. Cliquez sur Enregistrer pour créer le webhook.

Conditions requises pour le service de webhook

Votre service de webhook doit remplir les conditions suivantes :

• Il doit gérer les requêtes HTTPS. Le protocole HTTP n'est pas compatible. Si vous hébergez votre service de webhook sur Google Cloud Platform à l'aide d'une solution de calcul ou de calcul sans serveur, consultez la documentation produit pour la diffusion avec HTTPS. Pour connaître les autres options d'hébergement, consultez la page Obtenir un certificat SSL pour votre domaine.
• Son URL pour les requêtes doit être accessible publiquement. sauf s'il est hébergé en tant que fonction Cloud Run ou qu'il est accessible en tant que webhook de Annuaire des services.
• Il doit gérer les requêtes et les réponses comme décrit dans le webhook standard ou webhook flexible.
• Si votre agent n'intègre pas l'accès au réseau privé de l'annuaire des services, les appels webhook sont considérés comme extérieurs au périmètre de service et sont bloqués lors de l'activation de VPC Service Controls. L'annuaire des services accepte les points de terminaison limités. Pour en savoir plus, consultez l'annuaire des services.

Authentification

Remarque : Les adresses IP sources des webhooks font partie du sous-ensemble de celles listées sur https://www.gstatic.com/ipranges/goog.json, qui exclut celles figurant sur https://www.gstatic.com/ipranges/cloud.json. En outre, Dialogflow ne peut fournir aucune garantie sur les plages d'adresses IP des machines qui envoient des requêtes webhook. Plutôt que de limiter l'accès à l'aide d'une plage d'adresses IP, utilisez l'une des méthodes d'authentification indiquées dans le tableau ci-dessous.

Il est important de sécuriser votre service de webhook, de sorte que vous seul ou votre agent Dialogflow soyez autorisé à effectuer des requêtes. Cette configuration se fait lors de la création d'une ressource webhook. Dialogflow CX est compatible avec les mécanismes d'authentification suivants :

Terme	Définition
En-têtes d'authentification	Pour les paramètres de webhook, vous pouvez spécifier des paires clé/valeur facultatives dans l'en-tête HTTP. S'ils sont fournis, Dialogflow ajoute ces en-têtes HTTP aux requêtes webhook. Il est courant de fournir une seule paire avec une clé authorization. Les valeurs d'en-tête sont compatibles avec les références de paramètre de session et l'analyse des fonctions système, comme dans les messages de réponse statique.
Authentification de base avec nom d'utilisateur et mot de passe	Pour les paramètres de webhook, vous pouvez spécifier des valeurs de nom d'utilisateur et de mot de passe de connexion facultatives. S'il est fourni, Dialogflow ajoute un en-tête HTTP d'autorisation aux requêtes webhook. Cet en-tête se présente sous la forme suivante : "authorization: Basic <base 64 encoding of the string username:password>".
OAuth tiers	Vous pouvez spécifier la configuration OAuth tierce afin que Dialogflow échange un jeton d'accès auprès du fournisseur OAuth et l'ajoute dans l'en-tête HTTP d'autorisation. Seul le flux d'identifiants client est accepté.
Jetons d'accès de l'agent de service	Vous pouvez sélectionner le jeton d'accès dans l'authentification de l'agent de service pour utiliser les jetons d'accès de l'agent de service pour l'authentification. Cela permet d'accéder à d'autres API Google Cloud.
Jetons d'ID d'agent de service	Vous pouvez sélectionner le jeton d'identification dans l'authentification de l'agent de service pour utiliser des jetons d'ID d'agent de service pour l'authentification. Cela permet d'accéder aux fonctions Cloud Run et aux services Cloud Run.
Authentification TLS mutuelle	Consultez la documentation sur l'authentification TLS mutuelle.

Remarque :Si plusieurs options d'authentification sont activées, celles dont la priorité est la plus élevée prévalent. Ordre de priorité des options d'authentification: En-têtes d'authentification, Authentification de base, OAuth tiers, Authentification de l'agent de service.

Validation des certificats HTTPS

Dialogflow utilise par défaut le trust store par défaut de Google pour valider les certificats HTTPS. Si vous avez l'intention d'utiliser des certificats non reconnus par le magasin de confiance par défaut de Google pour votre serveur HTTPS, tels que des certificats autosignés ou des certificats racines personnalisés, consultez la pageCertificats CA personnalisés.

Webhooks spécifiques à l'environnement

Si vous utilisez des environnements pour isoler les systèmes de production des systèmes de développement (recommandé), vous pouvez configurer vos webhooks pour qu'ils soient spécifiques à l'environnement. Pour chaque ressource de webhook que vous définissez, vous pouvez fournir une URL unique et des paramètres d'authentification pour chaque environnement que vous avez défini pour l'agent.

Vous pouvez ainsi développer et tester de manière sécurisée les mises à jour de votre code de webhook avant de les déployer en production.

Créer ou modifier des ressources webhook

Une fois que vous avez un service de webhook en cours d'exécution, vous devez créer une ressource de webhook contenant les informations de connectivité et d'authentification. Après la création, vous pouvez également modifier les paramètres des ressources de webhook à tout moment.

Pour créer ou modifier une ressource de webhook :

Console

1. Ouvrez la console Dialogflow CX.
2. Choisissez votre projet Google Cloud.
3. Sélectionnez votre agent.
4. Sélectionnez l'onglet Gérer.
5. Cliquez sur Webhooks.
6. Cliquez sur Créer ou sur une ressource de webhook dans la liste pour la modifier.
7. Saisissez les paramètres de ressources de webhook standards. ou les paramètres de ressources de webhooks flexibles.
8. Cliquez sur Enregistrer.

API

Pour créer une ressource de webhook, consultez la méthode create pour le type Webhook. Pour modifier une ressource webhook (à l'exception des paramètres spécifiques à l'environnement), consultez la méthode patch ou update pour le type Webhook. Accéder à la documentation de référence de l'API Webhook

Sélectionnez un protocole et une version pour la référence du webhook :

Protocole	V3	V3beta1
REST	Ressource Webhook	Ressource de webhook
RPC	Interface Webhook	Interface Webhook
C++	WebhooksClient	Non disponible
C#	WebhooksClient	Non disponible
Go	WebhooksClient	Non disponible
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Non disponible	Non disponible
Python	WebhooksClient	WebhooksClient
Ruby	Non disponible	Non disponible

Fermer

Pour modifier les paramètres spécifiques à l'environnement d'un webhook, consultez la méthode patch ou update pour le type Environment. Accéder à la documentation de référence de l'API Environment

Sélectionnez un protocole et une version pour la référence de l'environnement :

Protocole	V3	V3beta1
REST	Ressource d'environnement	Ressource d'environnement
RPC	Interface de l'environnement	Interface de l'environnement
C++	EnvironmentsClient	Non disponible
C#	EnvironmentsClient	Non disponible
Go	EnvironmentsClient	Non disponible
Java	EnvironmentsClient	EnvironmentsClient
Node.js	EnvironmentsClient	EnvironmentsClient
PHP	Non disponible	Non disponible
Python	EnvironmentsClient	EnvironmentsClient
Ruby	Non disponible	Non disponible

Fermer

Erreurs de webhook

Si votre service de webhook rencontre une erreur lors du traitement d'une requête de webhook, votre code de webhook doit renvoyer l'un des codes d'état HTTP suivants :

• 400 Requête incorrecte
• 401 Opération non autorisée
• 403 Interdit
• 404 Introuvable
• 500 Panne du serveur
• 503 Service indisponible

Dans toutes les situations d'erreur suivantes, Dialogflow appelle une erreur de webhook ou un événement intégré, et continue le traitement comme d'habitude :

• Expiration du délai de réponse
• Code d'état d'erreur reçu
• Réponse non valide
• Service de webhook non disponible

En outre, si l'appel de service de webhook a été déclenché par un appel d'API de détection d'intent, le champ queryResult.webhookStatuses de la réponse de détection d'intent contient les informations d'état du webhook.

Utiliser les fonctions Cloud Run

Remarque :Cette section explique comment utiliser des fonctions Cloud Run sécurisées. pour les webhooks Dialogflow. Nous vous recommandons de sécuriser vos fonctions. Toutefois, si vous choisissez de vous authentifier avec un nom d'utilisateur et un mot de passe basés sur une URL, ou des en-têtes HTTP, vous devez autoriser les accès non authentifiés à votre fonction.

Dialogflow s'intègre aux fonctions Cloud Run pour vous permettre de créer facilement un webhook sécurisé sans serveur. Si vous créez une fonction qui se trouve dans le même projet que votre agent, il vous suffit de sélectionner Service Agent Auth -> Jeton d'ID dans la configuration d'authentification, votre agent peut ensuite appeler votre webhook de manière sécurisée.

Toutefois, il existe deux situations dans lesquelles vous devez configurer manuellement cette intégration :

1. Le compte de service Agent de service Dialogflow avec l'adresse suivante doit exister pour votre projet d'agent :

   [e-mail]

   Ce compte de service spécial et la clé associée est normalement créé automatiquement lorsque vous créez le premier agent pour un projet. Si votre agent a été créé avant le 1er novembre 2020, vous pouvez déclencher la création de ce compte de service spécial :
   1. Créez un agent pour le projet.
   2. Exécutez la commande suivante :

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

2. Si votre fonction de webhook se trouve dans un projet différent de celui de l'agent, vous devez fournir le rôle IAM Demandeur Cloud Functions à l'agent de service Dialogflow dans le projet de votre fonction.
3. Sélectionnez Service Agent Auth -> (Authentification de l'agent de service ->) Jeton d'ID dans la section de configuration de l'authentification.

Utiliser des webhooks conteneurisés et le framework Go ezcx

Si vous souhaitez implémenter un webhook conteneurisé à l'aide de Go, consultez le framework ezcx Go. Ce framework peut simplifier de nombreuses étapes requises lors de la création d'un webhook.

Utiliser des fonctions Cloud Run avec un trafic interne uniquement

Remarque :L'utilisation de fonctions Cloud Run en dehors du périmètre VPC Service Controls de Les projets d'agent Dialogflow pour les webhooks ne sont pas compatibles.

des fonctions Cloud Run configurées pour accepter le trafic interne provenant de réseaux VPC dans le ou le même périmètre VPC SC peut être utilisé comme webhook tant que le se trouve dans le même projet ou le même périmètre VPC SC.

Utiliser l'Annuaire des services pour l'accès privé au réseau

Dialogflow s'intègre à l'accès au réseau privé de l'Annuaire des services pour pouvoir se connecter aux cibles de webhooks dans votre réseau VPC. Cela permet de conserver le trafic au sein du réseau Google Cloud et d'appliquer IAM et VPC Service Controls.

Pour configurer un webhook ciblant un réseau privé, procédez comme suit :

1. Suivez la page sur la configuration du réseau privé de l'Annuaire des services pour configurer votre réseau VPC et le point de terminaison de l'Annuaire des services.

   Remarque :Dialogflow met en cache les informations de l'annuaire des services pendant 90 secondes. Cela signifie que si vous mettez à jour le point de terminaison de l'Annuaire des services, la modification prendra 90 secondes. De plus, si vous configurez plusieurs points de terminaison pour la redondance, Dialogflow peut envoyer du trafic via un point de terminaison en échec pendant 90 secondes.

2. Le compte de service Agent de service Dialogflow avec l'adresse suivante doit exister pour votre projet d'agent :

   [e-mail]

   Attribuez les rôles IAM suivants au compte de service Agent de service Dialogflow :
   • servicedirectory.viewer du projet de l'Annuaire des services
   • servicedirectory.pscAuthorizedService du projet réseau

3. Fournissez le service d'annuaire du service avec l'URL et les informations d'authentification facultatives lors de la création du webhook.

   Console

   

   API

   Consultez le champ serviceDirectory pour le type Webhook. Accéder à la documentation de référence de l'API Webhook

   Sélectionnez un protocole et une version pour la référence du webhook :

   Protocole	V3	V3beta1
   REST	Ressource de webhook	Ressource de webhook
   RPC	Interface Webhook	Interface Webhook
   C++	WebhooksClient	Non disponible
   C#	WebhooksClient	Non disponible
   Go	WebhooksClient	Non disponible
   Java	WebhooksClient	WebhooksClient
   Node.js	WebhooksClient	WebhooksClient
   PHP	Non disponible	Non disponible
   Python	WebhooksClient	WebhooksClient
   Ruby	Non disponible	Non disponible

   Fermer

Pour résoudre les problèmes, vous pouvez configurer un test de disponibilité privé pour vérifier que l'annuaire des services est correctement configuré.

Authentification de l'agent de service

Dialogflow peut générer ID token (Jeton d'ID) ou jeton d'accès avec Agent de service Dialogflow.

Le jeton est ajouté dans l'en-tête HTTP d'autorisation lorsque Dialogflow appelle un webhook.

Jeton d'ID

Un jeton d'ID peut être utilisé pour accéder aux fonctions et services Cloud Run une fois que vous avez accordé le rôle "Demandeur" à

[e-mail]

Si les fonctions Cloud Run et les services Cloud Run se trouvent dans le même projet de ressources, vous n'avez pas besoin une autorisation IAM pour les appeler.

L'audience utilisée pour générer le jeton d'ID correspond à l'URL complète du webhook, à l'exception des paramètres de requête. Si vous utilisez Cloud Run, assurez-vous que cette URL est compatible avec les audiences Cloud Run. Par exemple, si l'URL de webhook est

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

L'URL suivante doit figurer dans les audiences personnalisées.

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

Les webhooks peuvent aussi valider le jeton à l'aide de bibliothèques clientes Google ou de bibliothèques Open Source github.com/googleapis/google-auth-library-nodejs.

Jeton d'accès

Un jeton d'accès peut être utilisé pour accéder à d'autres API Google Cloud une fois que vous avez attribué les rôles requis à

[e-mail]

Exemples et dépannage

Consultez le guide d'utilisation des webhooks.