Webhook

Les webhooks sont des services qui hébergent votre logique métier. Au cours d'une session, les webhooks vous permettent d'utiliser les données extraites par le traitement du langage naturel de Dialogflow pour générer des réponses dynamiques, valider les données collectées ou déclencher des actions sur le backend.

Les webhooks CX ressemblent aux webhooks ES, sauf que les champs de demande et de réponse ont été modifiés pour prendre en charge les fonctionnalités CX.

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.
• Il doit gérer les requêtes POST avec un corps JSON WebhookRequest.
• Il doit répondre aux requêtes WebhookRequest avec un corps JSON WebhookResponse.

Authentification

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 :

• L'authentification avec des en-têtes d'authentification
• Utiliser Cloud Functions
• Jetons d'identité de service
• Authentification TLS mutuelle

Requête de webhook

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 contenant des informations sur l'intent mis en correspondance.

Remarque : La documentation JSON REST pour ce type doit être la référence principale, car ce type est envoyé uniquement via le protocole JSON REST. En raison d'un bug de génération de documentation interne, la documentation de ce type ne peut pas être produite pour REST. Veuillez consulter la description des champs dans la documentation RPC et traduire au format JSON jusqu'à ce que ce bug soit résolu.

Pour plus d'informations, consultez la documentation de référence du message WebhookRequest.

Réponse webhook

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

Remarque : La documentation JSON REST de ce type doit être la référence principale, car ce type n'est envoyé que via le protocole JSON REST. En raison d'un bug de génération de documentation interne, la documentation de ce type ne peut pas être produite pour REST. Veuillez consulter la description des champs dans la documentation RPC et traduire au format JSON jusqu'à ce que ce bug soit résolu.

Pour plus d'informations, consultez la documentation de référence du message WebhookResponse.

Créer une ressource de 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. Pour créer une ressource de webhook, procédez comme suit :

Console

1. Ouvrez la console Dialogflow CX.
2. Choisissez votre projet GCP.
3. Sélectionnez votre agent.
4. Sélectionnez l'onglet Gérer.
5. Cliquez sur Webhooks.
6. Cliquez sur Créer.
7. Saisissez les données du webhook.
8. Cliquez sur Save.

API

Consultez la méthode create 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 du webhook	Interface du webhook
C#	Non disponible	Non disponible
Go	Non disponible	Non disponible
Java	WebhooksClient	WebhooksClient
Node.js	WebhooksClient	WebhooksClient
PHP	Non disponible	Non disponible
Python	WebhooksClient	WebhooksClient
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 Cloud Functions

Dialogflow s'intègre à Cloud Functions pour vous permettre de créer facilement un webhook sécurisé sans serveur. Si vous créez une fonction résidant dans le même projet que votre agent, celui-ci peut appeler votre webhook en toute sécurité sans configuration particulière.

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

Jetons d'identité de service

Lorsque Dialogflow appelle un webhook, il fournit un jeton d'identité Google avec la requête. N'importe quel webhook peut valider le jeton à l'aide de bibliothèques clientes Google ou de bibliothèques Open Source telles que github.com/googleapis/google-auth-library-nodejs.