Webhooks

Les webhooks sont des services qui hébergent votre logique métier ou appellent d'autres services. Lors d'une session, les webhooks vous permettent d'utiliser les données extraites par le 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 CX. Avec un webhook flexible, vous définissez les champs de requête et de réponse.

Vous pouvez également accéder au code d'état HTTP de l'appel de webhook à l'aide du paramètre de requête $request.webhook_status_code.

Webhooks standards

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

Requête de webhook standard

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

Certaines intégrations renseignent le champ WebhookRequest.payload avec des informations supplémentaires. Par exemple, l'intégration de Dialogflow CX Phone Gateway fournit l'ID 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 de webhook standard

Une fois que votre service de webhook reçoit une requête, il doit envoyer une réponse qui répond aux exigences suivantes :

• La réponse doit avoir lieu dans le délai avant expiration configuré lors de la création de la ressource de webhook.
• La réponse ne doit pas dépasser 64 Kio.

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

Paramètres des ressources de webhook standards

Le tableau suivant décrit les paramètres de ressource des webhooks standards :

X	Élément
Nom à afficher	Nom affiché dans la console pour le webhook.
Délai avant expiration du webhook	Lorsque Dialogflow CX envoie une requête HTTP à votre service de webhook, ce paramètre contrôle le délai avant expiration en secondes pour chaque tentative de requête individuelle, et non pour l'ensemble du tour de conversation. Si une tentative expire ou échoue avec une erreur temporaire, Dialogflow CX effectue automatiquement une nouvelle tentative. Cette nouvelle tentative peut entraîner un délai d'exécution total pouvant atteindre le double de la valeur de délai avant expiration configurée avant de renvoyer une erreur. Si un délai avant expiration se produit après une nouvelle tentative, Dialogflow CX appelle un événement webhook.error.timeout. Pour en savoir plus, consultez Nouvelles tentatives automatiques.
Type	Définissez cette option sur Annuaire des services si vous utilisez l'annuaire des services pour l'accès au réseau privé. Sinon, définissez-la sur Service Web générique.
URL du webhook	Indiquez l'adresse URL de votre service de webhook.
Sous-type	Définissez cette option sur Standard.
Webhook spécifique à l'environnement	Vous pouvez fournir des webhooks spécifiques à l'environnement.
Authentification	Consultez la section Authentification.
Certificat CA personnalisé	Cette option permet d'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, ainsi que les champs des messages de requête et de réponse. La requête ne peut fournir que les valeurs de paramètres sélectionnées, et la réponse ne peut fournir que les valeurs de remplacement des paramètres. Cela simplifie l'interface entre l'agent et le webhook, car il est rarement nécessaire de communiquer autre chose que les valeurs des paramètres de session. 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 de webhook uniques pour différents scénarios.

Requête de webhook flexible

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

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

Pour envoyer des valeurs de paramètre de session à l'aide de l'URL de la requête ou du corps JSON, utilisez des références de paramètre. Vous n'avez pas besoin d'échapper la référence du paramètre dans l'URL ni de l'encapsuler entre guillemets. Au moment de l'exécution, Dialogflow CX échappe 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 l'encadrer de guillemets, quel que soit le type du paramètre. Si le paramètre est en fait une valeur scalaire, de liste ou composite numérique, Dialogflow CX 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 scalaire, de liste ou composite numérique est référencée dans une valeur de chaîne (par exemple, "This is a number: $session.params.size"), le paramètre est traité comme une chaîne ("This is a number: 3").

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

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

Et au corps JSON de la requête comme suit :

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

Réponse de webhook flexible

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

Votre réponse doit respecter les limites suivantes :

• La réponse doit avoir lieu dans le délai avant expiration configuré lors de la création de la ressource de webhook. Sinon, la requête expirera.
• La taille de la réponse ne doit pas dépasser 64 Kio.

Pour spécifier un champ scalaire, de liste ou composite, utilisez le format suivant :

$.fully.qualified.path.to.field

Prenons l'exemple de la réponse JSON suivante :

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

Pour spécifier le champ "value", utilisez les éléments suivants :

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

Paramètres flexibles des ressources de webhook

Le tableau suivant décrit les paramètres de ressource des webhooks flexibles.

X	Élément
Nom à afficher	Nom affiché dans la console pour le webhook.
Délai avant expiration du webhook	Lorsque Dialogflow CX envoie une requête HTTP à votre service de webhook, ce paramètre contrôle le délai avant expiration en secondes pour chaque tentative de requête individuelle, et non pour l'ensemble du tour de conversation. Si une tentative expire ou échoue avec une erreur temporaire, Dialogflow CX effectue automatiquement une nouvelle tentative. Cette nouvelle tentative peut entraîner un délai d'exécution total pouvant atteindre le double de la valeur de délai avant expiration configurée avant de renvoyer une erreur. Si un délai avant expiration se produit après une nouvelle tentative, Dialogflow CX appelle un événement webhook.error.timeout. Pour en savoir plus, consultez Nouvelles tentatives automatiques.
Type	Définissez cette option sur Annuaire des services si vous utilisez l'annuaire des services pour l'accès au réseau privé. Sinon, définissez-la 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 aux paramètres de session.
Sous-type	Définissez cette option sur Flexible.
Méthode	Définissez la méthode HTTP pour la requête de webhook.
Corps de la requête	Fournissez le corps JSON de la requête comme décrit ci-dessus.
Configuration de la réponse	Fournissez les paramètres de session qui doivent être définis sur 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é	Cette option permet d'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 à Salesforce CRM.

1. Accédez à l'onglet Gérer, sélectionnez Webhooks, puis cliquez sur Créer.
2. Sous Sous-type, sélectionnez Flexible.
3. Cliquez sur Configurer à l'aide d'un modèle prédéfini.
4. Dans le menu Type d'intégration, sélectionnez Salesforce.
5. Dans le menu Nom de l'API, sélectionnez un nom d'API. Le modèle remplit automatiquement le formulaire de webhook en fonction du nom d'API que vous choisissez.
   1. Configurez manuellement les champs suivants, le cas échéant, en fonction de vos paramètres :
      • URL du webhook
      • Méthode
      • Corps de la requête JSON
      • Configuration de la réponse
   2. Les champs OAuth obligatoires seront mis en surbrillance dans la section Authentification.
6. Cliquez sur Enregistrer.

Conditions requises pour le service de webhook

Votre service de webhook doit répondre aux exigences suivantes :

• Gérer les requêtes HTTPS Le protocole HTTP n'est pas compatible. Si vous hébergez votre service de webhook sur Google Cloud à l'aide d'une solution Compute ou d'informatique sans serveur, consultez la documentation sur la diffusion avec HTTPS. Pour connaître les autres options d'hébergement, consultez Obtenir un certificat SSL pour votre domaine.
• Assurez-vous que l'URL du service de webhook est accessible publiquement, sauf s'il est hébergé en tant que ressource Cloud Run ou s'il est accessible en tant que webhook de l'Annuaire des services.
• Gérez les requêtes et les réponses comme décrit dans la section Webhook standard ou Webhook flexible.
• Si votre agent ne s'intègre pas à l'accès au réseau privé de l'Annuaire des services, les appels de webhook se trouvent en dehors du périmètre de service et sont bloqués lorsque vous activez VPC Service Controls. L'Annuaire des services est compatible avec un nombre limité de points de terminaison. Pour en savoir plus, consultez Annuaire des services.

Authentification

Sécurisez votre service de webhook afin que seuls vous ou votre agent Dialogflow CX puissiez effectuer des requêtes. Configurez ce paramètre lorsque vous créez ou modifiez une ressource de webhook. Dialogflow CX est compatible avec les mécanismes d'authentification suivants :

X	Élément
En-têtes d'authentification	Pour les paramètres de webhook, vous pouvez spécifier des paires clé/valeur d'en-tête HTTP facultatives. S'ils sont fournis, Dialogflow CX ajoute ces en-têtes HTTP aux requêtes de webhook. Il est courant de fournir une seule paire avec une clé de authorization. Les valeurs d'en-tête sont compatibles avec les références de paramètres de session et l'analyse des fonctions système, comme dans les messages de réponse statiques. Si vous utilisez un identifiant statique pour l'en-tête authorization, nous vous recommandons de le fournir à l'aide de Secret Manager.
Authentification de base avec nom d'utilisateur et mot de passe	Pour les paramètres de webhook, vous pouvez spécifier des valeurs facultatives de nom d'utilisateur et de mot de passe de connexion. S'il est fourni, Dialogflow CX ajoute un en-tête HTTP d'autorisation aux requêtes de webhook. Cet en-tête se présente sous la forme suivante : "authorization: Basic <base 64 encoding of the string username:password>". Nous vous recommandons de fournir votre nom d'utilisateur et votre mot de passe à l'aide de Secret Manager.
OAuth tiers	Vous pouvez spécifier la configuration OAuth tierce afin que Dialogflow CX échange un jeton d'accès du système OAuth et l'ajoute dans l'en-tête HTTP d'autorisation. Seul le flux d'identifiants client est accepté. Nous vous recommandons de fournir votre code secret du client à l'aide de Secret Manager.
Jetons d'accès de l'agent de service	Arrêt.
Compte de service	Vous pouvez utiliser un compte de service pour l'authentification. Il peut être utilisé pour accéder à d'autres API Google Cloud .
Jetons d'ID d'agent de service	Vous pouvez choisir "Jeton d'ID" dans la section "Authentification de l'agent de service", ce qui vous permet d'utiliser le jeton d'ID de l'agent de service pour l'authentification. Cela vous permet d'accéder aux ressources Cloud Run.
Authentification TLS mutuelle	Consultez la documentation sur l'authentification TLS mutuelle.

Remarque : Si plusieurs options d'authentification sont activées, les options de priorité supérieure prévalent. L'ordre de priorité est le suivant : en-têtes d'authentification, authentification de base, OAuth tiers, authentification de l'agent de service.

Remarque : Nous vous déconseillons d'utiliser des plages d'adresses IP pour authentifier les requêtes de webhook. Si vous choisissez d'utiliser l'adresse IP source de la requête pour activer la connectivité dans votre périmètre réseau, autorisez les requêtes provenant des plages répertoriées sur la page https://www.gstatic.com/ipranges/goog.json et refusez les connexions provenant des plages répertoriées sur la page https://www.gstatic.com/ipranges/cloud.json (il s'agit des adresses de Google qui peuvent être utilisées pour déployer des charges de travail tierces). Dialogflow ne peut pas garantir les plages d'adresses IP pour les machines qui envoient des requêtes de webhook.

Remarque : Après le 15 août 2025, les agents exportés ne contiendront plus d'identifiants de valeur brute pour les en-têtes d'authentification, l'authentification de base avec nom d'utilisateur et mot de passe, ou OAuth tiers.

OAuth tiers

Dialogflow CX collecte un jeton d'accès auprès d'un fournisseur OAuth tiers et l'ajoute à l'en-tête HTTP d'autorisation lors de l'envoi de requêtes de webhook.

Le tableau suivant décrit les paramètres de ressources pour OAuth tiers :

X	Élément
ID client	ID client à utiliser lors de la demande d'un jeton OAuth.
Code secret du client	Secret à utiliser lors de la demande d'un jeton OAuth. Nous vous recommandons de fournir votre code secret du client à l'aide de Secret Manager.
URL du point de terminaison OAuth	URL à utiliser pour demander un jeton OAuth.
Champs d'application OAuth	Liste de champs d'application séparés par une virgule pour lesquels le jeton OAuth peut être utilisé.

Les requêtes envoyées à l'URL du point de terminaison OAuth pour recevoir un jeton n'incluent pas les en-têtes de requête personnalisés configurés pour la requête de webhook. Vous pouvez transmettre des informations personnalisées au serveur OAuth en tant que paramètres dans la chaîne de requête de l'URL du point de terminaison OAuth.

Remarque : Les jetons OAuth tiers sont réutilisés pour les requêtes de webhook utilisant le même ID client, la même URL de point de terminaison et les mêmes champs d'application au sein du même agent Dialogflow CX, tant que la requête est effectuée sur le même serveur Dialogflow CX et que le jeton n'a pas expiré. Pour assurer une haute disponibilité, les agents sont déployés sur de nombreux serveurs individuels qui ne partagent pas les caches de jetons OAuth. Lorsque vous déployez une solution qui utilise des jetons OAuth tiers, envisagez d'implémenter un proxy d'API pour gérer le volume de requêtes que votre agent peut envoyer à votre fournisseur OAuth tiers.

Jeton d'ID de l'agent de service

Dialogflow CX peut générer un jeton d'ID à l'aide de l'agent de service Dialogflow CX. Ce jeton est ajouté à l'en-tête HTTP d'autorisation lorsque Dialogflow CX appelle un webhook.

Un jeton d'ID peut être utilisé pour accéder aux ressources Cloud Run après avoir attribué le rôle Demandeur Cloud Run (roles/run.invoker) à

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

Si les ressources Cloud Run se trouvent dans le même projet de ressources, vous n'avez pas besoin d'autorisations IAM (Identity and Access Management) supplémentaires pour les appeler.

L'audience utilisée pour générer le jeton d'ID est l'URL de webhook complète, à l'exclusion 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

Tout webhook peut également valider le jeton à l'aide des bibliothèques clientes Google ou de bibliothèques Open Source telles que la bibliothèque Google Auth pour Node.js.

Si votre webhook est hébergé sur Cloud Run et accessible via un équilibreur de charge, ajoutez l'URL de votre équilibreur de charge en tant qu'audience personnalisée à votre service Cloud Run. Pour en savoir plus sur les audiences personnalisées, consultez Définir des audiences personnalisées pour les services.

Compte de service

Les comptes de service peuvent être utilisés pour authentifier les requêtes de webhook auprès de toutes les API Google compatibles.

Si vous ne l'avez pas encore fait, créez un compte de service.

Comme les comptes de service sont des comptes principaux, ils peuvent accéder aux ressources de votre projet en leur attribuant un rôle, comme n'importe quel autre compte principal. L'adresse e-mail du compte de service est utilisée pour générer un jeton d'accès qui est envoyé dans l'en-tête Authorization de la requête de webhook.

Pour configurer le webhook afin qu'il utilise des comptes de service, vous devez disposer des autorisations suivantes :

• roles/iam.serviceAccountUser

Pour générer des jetons, l'agent de service Dialogflow doit disposer des autorisations suivantes :

• roles/iam.serviceAccountTokenCreator

Le compte de service doit également disposer des autorisations nécessaires pour accéder au service qui héberge le webhook.

Remarque : Si vous essayez d'utiliser des comptes de service dans plusieurs projets, assurez-vous que votre règle d'administration le permet. Les deux autorisations doivent être accordées dans le projet contenant le compte de service.

Authentification Secret Manager

Si vous utilisez des en-têtes d'authentification, l'authentification de base avec un nom d'utilisateur et un mot de passe, ou OAuth tiers, vous pouvez stocker les identifiants en tant que secrets à l'aide de Secret Manager. Voici les étapes nécessaires pour authentifier votre webhook à l'aide de secrets :

1. Créez votre secret si vous n'en avez pas.
2. Attribuez à l'agent de service Dialogflow le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le nouveau secret.
3. Copiez vos identifiants dans le presse-papiers.
4. Ajoutez une version de secret à votre secret et collez vos identifiants en tant que valeur du secret :
   • Si vous utilisez des en-têtes d'authentification, saisissez Bearer <YOUR_CREDENTIAL>.
   • Si vous utilisez l'authentification de base par nom d'utilisateur et mot de passe, saisissez <YOUR_USERNAME>:<YOUR_PASSWORD>.
   • Omettez tout caractère de nouvelle ligne à la fin.
5. Copiez le nom de la version du secret que vous avez ajoutée. Le format du nom est projects/<var>PROJECT_ID</var>/secrets/<var>SECRET_ID</var>/versions/<var>VERSION_ID</var>.
6. Ouvrez l'écran de modification du webhook.
7. Configurez les paramètres d'authentification :
   • Si vous utilisez des en-têtes d'authentification, créez un en-tête de requête de version de secret. Saisissez "Authorization" dans le champ Clé, puis collez le nom de la version du secret dans le champ Version du secret.
   • Pour l'authentification de base par nom d'utilisateur et mot de passe, cliquez sur Version du secret sous Authentification de base, puis collez le nom de la version du secret dans le champ Version du secret.
   • Si vous utilisez OAuth tiers, cliquez sur Version du secret sous OAuth tiers, puis collez le nom de la version du secret dans le champ Version du secret.
8. Cliquez sur Enregistrer.

Remarque : Nous n'acceptons que les secrets Secret Manager globaux. Nous n'acceptons pas les secrets régionaux.

Validation des certificats HTTPS

Par défaut, Dialogflow CX utilise le magasin de confiance par défaut de Google pour valider les certificats HTTPS. Si vous prévoyez 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 racine personnalisés, consultez Certificats CA personnalisés.

Webhooks spécifiques à l'environnement

Si vous utilisez des environnements pour isoler la production du développement, vous pouvez configurer vos webhooks pour qu'ils soient spécifiques à l'environnement. Vous pouvez fournir des paramètres d'URL et d'authentification spécifiques à l'environnement pour chaque ressource de webhook.

Cette configuration vous permet de développer et de tester en toute sécurité les mises à jour de votre code de webhook avant de les déployer en production.

Créer ou modifier des ressources de webhook

Une fois que vous disposez d'un service de webhook en cours d'exécution, créez une ressource de webhook dans votre agent, qui inclut des informations de connectivité et d'authentification. Vous pouvez modifier les paramètres de la ressource de webhook à tout moment.

Pour créer ou modifier une ressource de webhook :

Console

1. Ouvrez la console Dialogflow CX.
2. Accédez à votre projet.
3. Sélectionnez votre agent.
4. Cliquez sur l'onglet Gestion.
5. Cliquez sur Webhooks.
6. Cliquez sur Créer ou sélectionnez un webhook existant à modifier.
7. Configurez les paramètres de ressource de webhook standards ou les paramètres de ressource de webhook flexibles.
8. Cliquez sur Enregistrer.

API

Pour en savoir plus sur la création d'une ressource de webhook, consultez la méthode create pour le type Webhook. Pour en savoir plus sur la modification d'une ressource de 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 Webhook
RPC	Interface de webhook	Interface de 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 en savoir plus sur la modification des 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 d'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 : non autorisé
• 403 : Action interdite
• 404 : introuvable
• 500 : erreur du serveur
• 503 : Service non disponible

Dialogflow CX appelle un événement intégré d'erreur ou de délai d'expiration de webhook et poursuit le traitement comme d'habitude dans les situations d'erreur suivantes :

• Le délai avant expiration de la réponse est dépassé.
• Un code d'état d'erreur est reçu.
• La réponse n'est pas valide.
• Le service de webhook n'est pas disponible.

Si l'appel du 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.

Nouvelles tentatives automatiques

Dialogflow CX relance automatiquement les requêtes en cas d'erreurs de webhook afin d'améliorer la robustesse. Les nouvelles tentatives automatiques sont activées par défaut et ne peuvent pas être désactivées.

Dialogflow CX effectue une seule nouvelle tentative en cas d'échec temporaire, comme un délai d'expiration de requête, une connexion réseau interrompue ou un code d'état HTTP de la plage 5xx (par exemple, 500 Server fault ou 503 Service unavailable). Les erreurs de client de terminal, telles que le code d'état HTTP 404 Not found, échouent immédiatement sans nouvelle tentative.

Latence cumulée et budgétisation des délais avant expiration

Étant donné que Dialogflow CX effectue une nouvelle tentative en cas d'échec temporaire, un point de terminaison de webhook qui ne répond pas peut entraîner un délai d'exécution cumulé pouvant atteindre le double de la valeur de délai avant expiration configurée avant que Dialogflow CX ne renvoie une erreur. Par exemple, avec le paramètre de délai avant expiration par défaut de 5 secondes, un point de terminaison qui ne répond pas expire au bout de 5 secondes lors de la tentative initiale, puis expire au bout de 5 secondes supplémentaires lors de la nouvelle tentative. Cela entraîne une latence totale d'environ 10 secondes avant que Dialogflow CX n'appelle les gestionnaires d'erreurs, tels qu'un gestionnaire d'événements webhook.error.timeout ou sys.no-match-default.

Si votre architecture présente des limites strictes de latence en amont (par exemple, des systèmes de téléphonie ou de réponse vocale interactive (IVR) qui mettent fin aux appels après un délai de 10 secondes), prévoyez un budget pour les deux tentatives en définissant le délai avant expiration du webhook sur la moitié de la fenêtre autorisée (par exemple, entre 2,5 et 4 secondes).

Bonnes pratiques pour les nouvelles tentatives

Pour gérer efficacement les nouvelles tentatives dans votre service de webhook :

• Implémentez l'idempotence ou la déduplication des requêtes dans la logique de votre service de webhook pour traiter les requêtes en double de manière sécurisée.
• Si l'opération de votre webhook prend plus de temps que le délai avant expiration configuré, renvoyez immédiatement un code d'état HTTP 200 OK avec un message de remplacement, puis traitez la tâche de longue durée de manière asynchrone.

Utiliser Cloud Run

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

Dialogflow CX s'intègre à Cloud Run, ce qui vous permet de créer un webhook sans serveur sécurisé. Si vous créez une ressource Cloud Run qui réside dans le même projet que votre agent, sélectionnez Authentification de l'agent de service, puis Jeton d'ID dans la configuration de l'authentification afin que votre agent puisse appeler votre webhook de manière sécurisée.

Vous devez configurer manuellement cette intégration dans les deux situations suivantes :

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

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

   Ce compte de service spécial et la clé associée sont normalement créés automatiquement lorsque vous créez le premier agent d'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 réside dans un projet différent de celui de l'agent, vous devez attribuer le rôle IAM Demandeur Cloud Run ou Demandeur Cloud Functions au compte de service Agent de service Dialogflow CX dans votre projet de ressource Cloud Run.

Ensuite, sélectionnez Authentification de l'agent de service > Jeton d'ID dans la section Configuration de l'authentification.

Utiliser des webhooks conteneurisés et le framework Go ezcx

Pour implémenter un webhook conteneurisé à l'aide de Go, consultez le framework ezcx pour Go. Ce framework simplifie de nombreuses étapes requises pour créer un webhook.

Utiliser Cloud Run avec un trafic interne uniquement

Remarque : L'utilisation de Cloud Run en dehors du périmètre VPC Service Controls du projet d'agent Dialogflow CX pour les webhooks n'est pas acceptée.

Vous pouvez utiliser des ressources Cloud Run configurées pour accepter le trafic interne provenant de réseaux cloud privé virtuel (VPC) du même projet ou du même périmètre VPC Service Controls en tant que webhook, à condition que l'agent se trouve dans le même projet ou le même périmètre VPC Service Controls.

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

Dialogflow CX s'intègre à l'accès au réseau privé de l'Annuaire des services, ce qui lui permet de se connecter aux cibles de webhook de 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 les instructions de la section Configuration du réseau privé de l'Annuaire des services pour configurer votre réseau VPC et votre point de terminaison de l'Annuaire des services.

   Remarque : Dialogflow CX met en cache les informations de l'Annuaire des services pendant 90 secondes. Cela signifie que lorsque vous mettez à jour le point de terminaison de l'Annuaire des services, la modification prend 90 secondes.

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

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

   Attribuez les rôles suivants au compte de service Agent de service Dialogflow CX dans le projet où se trouve votre annuaire des services :

   • servicedirectory.viewer
   • servicedirectory.pscAuthorizedService

   De plus, si votre annuaire des services se trouve dans un projet différent de celui de votre agent Dialogflow CX, vous devez également attribuer le rôle servicedirectory.viewer au compte de l'agent de service Dialogflow CX dans le projet qui héberge votre agent Dialogflow CX.

3. Spécifiez le service Annuaire des services, l'URL et les informations d'authentification facultatives lorsque vous créez le 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 Webhook	Ressource Webhook
   RPC	Interface de webhook	Interface de 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é afin de vérifier que votre Annuaire des services est correctement configuré.

Exemples et dépannage

Pour en savoir plus, consultez le guide d'utilisation des webhooks.