Cette page a été traduite par l'API Cloud Translation.
Switch to English

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 :

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.

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.

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.

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

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 :
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    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.