Configuration de webhook

Pour ajouter les détails du webhook, procédez comme suit :

1. Pour l'assistant que vous souhaitez configurer, cliquez sur l'icône de , puis sélectionnez Paramètres.

2. Cliquez sur Webhooks > Post-message webhook.

3. Définissez le commutateur Webhook post-message sur Activé.

4. Dans l'événement Synchrone, sélectionnez l'une des options suivantes :

   • Continuer à traiter les données de l'utilisateur sans mettre à jour le webhook en cas d'erreur.

   • Renvoyer une erreur au client si l'appel au webhook échoue.

   Pour plus d'informations, voir Configuration de la gestion des erreurs des webhooks pour le post-traitement.

5. Dans la zone URL, ajoutez l'URL de l'application externe à laquelle vous souhaitez envoyer des appels de demande POST HTTP.

   Par exemple, vous stockez peut-être les réponses de votre assistant dans un système de gestion de contenu distinct. Lorsque l'assistant comprend l'entrée, l'action traitée renvoie un ID unique qui correspond à une réponse dans votre CMS. Pour appeler un service qui extrait une réponse de votre système de gestion des configurations pour un ID unique donné, indiquez l'URL de votre instance de service. Par exemple, https://example.com/get_answer.

   Vous devez spécifier une URL qui utilise le protocole SSL, donc indiquez une URL commençant parhttps.

6. Remplissez le champ Secret. Pour plus d'informations, voir Ajout d'un secret.

7. Dans le champ Délai d'attente, indiquez la durée (en secondes) pendant laquelle l'assistant doit attendre une réponse du webhook avant de renvoyer une erreur. La durée du délai d'attente ne peut pas être inférieure à 1 seconde ou supérieure à 30 secondes.

8. Dans la section En-têtes, cliquez sur Ajouter un en-tête + pour ajouter les en-têtes que vous souhaitez transmettre au service, un par un.

   Le service envoie automatiquement un en-tête Authorization avec un JWT. Si vous souhaitez gérer l'autorisation vous-même, ajoutez votre propre en-tête d'autorisation et le service l'utilisera à la place.

   Si l'application externe que vous appelez renvoie une réponse, elle peut être en mesure d'envoyer une réponse dans différents formats. Le webhook nécessite que la réponse soit formatée au format JSON. Le tableau suivant illustre comment ajouter un en-tête pour indiquer que vous souhaitez que la valeur résultante soit renvoyée au format JSON.

   Exemple d'en-tête

   Nom d'en-tête	Valeur d'en-tête
   Content-Type	application/json

9. Après avoir enregistré la valeur de l'en-tête, la chaîne est remplacée par des astérisques et ne peut plus être consultée.

10. Les détails du webhook sont sauvegardés automatiquement.

Ajout d'un secret

Ajoutez un secret client dans le champ Secret à transmettre avec la demande d'authentification auprès du service externe :

• Saisissez la clé sous la forme d'une chaîne de texte, par exemple purple unicorn.

• Utilisez un maximum de 1 024 caractères.

• N'utilisez pas de variables contextuelles.

Le service externe est responsable du contrôle et de la vérification du secret. Si aucun jeton n'est requis, indiquez n'importe quelle chaîne de caractères. Ce champ ne peut pas être laissé vide.

Pour afficher le secret au fur et à mesure que vous le saisissez, cliquez sur l' le mot de passe avant de le taper. Après avoir enregistré le secret, des astérisques remplacent la chaîne et vous ne pouvez plus la consulter.

Pour plus d'informations sur l'utilisation de cette zone, voir Sécurité Webhook.

Sécurité du webhook

Authentifier la demande de webhook en vérifiant le JSON Web Token (JWT) envoyé avec la demande. Le microservice de webhook génère automatiquement un JWT et l'envoie dans l'en-tête Authorization avec chaque appel de webhook :

• Pour les nouveaux webhooks ou les webhooks mis à jour par le biais de l'authentification par édition, l'en-tête d'autorisation est ignoré.

• Pour les webhooks existants dont l'en-tête d'authentification est enregistré, le bouton Modifier l'authentification est désactivé.

• La mise à jour d'un webhook existant pour utiliser la nouvelle configuration d'authentification modifie son comportement.

Si vous devez tester la vérification JWT, vous pouvez ajouter du code au service externe. Par exemple, si vous indiquez purple unicorn dans le champ Secret, vous pouvez utiliser le code suivant :

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Configuration de la gestion des erreurs du webhook pour le post-traitement

Vous pouvez décider de renvoyer une erreur dans l'étape de post-traitement si l'appel au webhook échoue. Deux options s'offrent à vous :

• Poursuivre le traitement des données de l'utilisateur sans mise à jour du webhook en cas d'erreur: L'assistant ignore les erreurs et traite le message sans le résultat du webhook. Si le post-traitement est utile mais pas indispensable, envisagez cette option.

• Renvoyer une erreur au client si l'appel au webhook échoue: Si le post-traitement est essentiel après l'envoi d'une réponse par l'assistant, sélectionnez cette option.

Lorsque vous activez l'option Renvoyer une erreur au client en cas d'échec de l'appel au webhook, tout s'arrête jusqu'à ce que l'étape de post-traitement soit terminée avec succès.

Tester régulièrement le processus externe afin d'identifier les défaillances potentielles. Si nécessaire, ajustez ce paramètre pour éviter des perturbations dans le traitement de la réponse.

Test du webhook

Testez votre webhook de manière approfondie avant de l'activer pour un assistant utilisé dans un environnement de production.

Le webhook n'est déclenché que lorsque votre assistant traite un message et qu'une réponse est prête à être renvoyée au canal.

Idenfication et traitement des incidents liés au webhook

Les codes d'erreur suivants peuvent vous aider à déterminer la cause des problèmes que vous pourriez rencontrer. Si vous avez une intégration de chat en ligne, par exemple, vous savez que votre webhook présente un problème si chaque message de test que vous envoyez renvoie un message tel que There is an error with the message you just sent, but feel free to ask me something else. Si ce message s'affiche, utilisez un outil API REST, tel que cURL,, pour envoyer une requête API /message de test, afin de voir le code d'erreur et le message complet qui est renvoyé.

Exemple de corps de demande

Il est utile de connaître le format du corps du webhook post-message de la demande afin que votre code externe puisse le traiter.

Le payload contient le corps de la réponse que votre assistant renvoie pour la version 2 de l'appel API /message, avec ou sans état. Le nom de l'événement message_processed indique que le webhook post-message génère la demande. Pour plus d'informations sur le corps de la demande de message, voir la référence API.

L'exemple suivant montre comment le corps d'une requête simple est formaté :

{
 "event": {
    "name": "message_processed"
},
"options": {},
"payload": {
    "output": {
        "intents": [
            {
                "intent": "General_Greetings",
                "confidence": 1
            }
        ],
        "entities": [],
        "generic": [
            {
                "response_type": "text",
                "text": "Hello. Good evening"
            }
        ]
    },
    "user_id": "test user",
    "context": {
        "global": {
            "system": {
                "user_id": "test user",
                "turn_count": 11
            },
            "session_id": "sxxx"
        },
        "skills": {
            "actions skill": {
                "user_defined": {
                    "var": "anthony"
                },
                "system": {
                    "state": "nnn"
                }
            }
        }
    }
}

Exemple 1

Cet exemple montre comment ajouter y'all à la fin de chaque réponse de l'assistant.

Dans la page de configuration du webhook post-message, les valeurs suivantes sont spécifiées :

• URL: https://your-webhook-url/
• Secret : aucun
• Nom de l'en-tête : Type-Contenu
• Valeur d'en-tête : application / json

Le webhook post-message appelle une action web IBM Cloud Functions nommée add_southern_charm.

Le code node.js de l'action Web add_southern_charmse présente comme suit :

function main(params) {
  console.log(JSON.stringify(params))
  if (params.payload.output.generic[0].text !== '') {
      //Get the length of the input text
        var length = params.payload.output.generic[0].text.length;
        //create a substring that removes the last character from the input string, which is typically punctuation.
        var revision = params.payload.output.generic[0].text.substring(0,length-1);
        const response = {
            body : {
                payload : {
                    output : {
                        generic : [
                              {
                                  //Replace the input text with your shortened revision and append y'all to it.
                                "response_type": "text",
                                "text": revision + ', ' + 'y\'all.'
                              }
                        ],
                    },
                },
            },
        };
        return response;
  }
  else {
    return {
        body : params
    }
  }
}

Exemple 2

Cet exemple montre comment traduire une réponse à un message dans la langue du client. Elle ne fonctionne que si vous suivez les étapes de l'exemple 2 pour définir un webhook de pré-message qui traduit le message original en anglais.

Définissez une séquence d'actions Web dans IBM Cloud Functions. La première action de la séquence vérifie la langue du texte entrant original, que vous avez stockée dans une variable contextuelle nommée original_input dans le code du webhook pré-message. La seconde action de la séquence traduit le texte de la réponse de la boîte de dialogue de l'anglais dans la langue d'origine utilisée par le client.

Dans la page de configuration du webhook post-message, les valeurs suivantes sont spécifiées :

• URL: https://your-webhook-url/
• Secret : aucun
• Nom de l'en-tête : Type-Contenu
• Valeur d'en-tête : application / json

Le code node.js pour la première action Web de votre séquence se présente comme suit :

let rp = require("request-promise");

function main(params) {
console.log(JSON.stringify(params))

if (params.payload.output.generic[0].text !== '') {
const options = { method: 'POST',
  url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/identify?version=2018-05-01',
  auth: {
           'username': 'apikey',
           'password': 'nnnn'
       },
  headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.context.skills['actions skill'].user_defined.original_input
  ],
  json: true,
};
     return rp(options)
    .then(res => {
      //Set the language property of the incoming message to the language that was identified by Watson Language Translator.
        params.payload.context.skills['actions skill'].user_defined['language'] = res.languages[0].language;
        console.log(JSON.stringify(params))
        return params;
})
}
else {
    params.payload.context.skills['actions skill'].user_defined['language'] = 'none';
    return param
}
};

La deuxième action Web de la séquence se présente comme suit :

let rp = require("request-promise");

function main(params) {
  console.log(JSON.stringify(params))
    if ((params.payload.context.skills["actions skill"].user_defined.language !== 'en') && (params.payload.context.skills["actions skill"].user_defined.language !== 'none')) {
    const options = { method: 'POST',
    url: 'https://api.us-south.language-translator.watson.cloud.ibm.com/instances/572b37be-09f4-4704-b693-3bc63869nnnn/v3/translate?version=2018-05-01',
    auth: {
            'username': 'apikey',
            'password': 'nnn'
        },
    body: {
        text: [
            params.payload.output.generic[0].text
            ],
            target: params.payload.context.skills["actions skill"].user_defined.language
    },
    json: true
    };
      return rp(options)
      .then(res => {
          params.payload.context.skills["actions skill"].user_defined["original_output"] = params.payload.output.generic[0].text;
          params.payload.output.generic[0].text = res.translations[0].translation;
          return {
            body : params
          }
  })
  }
  return {
    body : params
  }
};

Retrait du webhook

Si vous ne souhaitez pas traiter les réponses aux messages à l'aide d'un webhook, procédez comme suit :

1. Pour l'assistant que vous souhaitez configurer, cliquez sur l'icône de , puis sélectionnez Paramètres.

2. Cliquez sur Webhooks > Post-message webhook.

3. Effectuez l'une des opérations suivantes :

• Pour ne plus appeler un webhook pour traiter chaque message entrant, réglez le commutateur Post-message webhook sur Désactivé.

• Pour modifier le webhook que vous souhaitez appeler, cliquez sur Supprimer le webhook.