Webhook 配置

要添加 Webhook 详细信息，请完成以下步骤：

1. 对于要配置的助手，单击 图标，然后选择设置。

2. 单击 Webhooks > Pre-message webhook。

3. 将预发信息 webhook 开关设置为已启用。

4. 在同步事件中，从以下选项中选择一个：

   • 如果出现错误，则继续处理用户输入，不更新 webhook。

   • 如果网络钩子调用失败，则向客户端返回错误信息。

   更多信息，请参阅 为预处理配置 webhook 错误处理。

5. 在 URL 字段中，添加要向其发送 HTTP POST 请求调出的外部应用程序的 URL。

   例如，您可以编写一个 Cloud Functions 网页操作，检查信息是否使用英语以外的语言，然后将其发送到 Language Translator 服务，将其转换为英语。 为网络操作指定 URL，如本示例所示：

   https://us-south.functions.cloud.ibm.com/api/v1/web/my_org_dev/default/translateToEnglish.json
   

   您必须指定一个使用 SSL 协议的 URL，因此请指定一个以 https 开头的 URL。

6. 填写秘密字段。 更多信息，请参阅 添加秘密。

7. 在“超时”字段中，指定助手在返回错误之前等待网络钩子响应的时间长度（秒）。 超时时间不能短于 1 秒或长于 30 秒。

8. 在“标头”部分，单击“添加标头 +”，一次添加一个要传递给服务的标头。

   如果您调用的外部应用程序返回响应，它可能会以不同的格式发送响应。 网络钩子要求以 JSON 格式作出响应。 下表说明了如何添加标头，以表明您希望返回 JSON 格式的结果值。

   头示例

   头名称	头值
   Content-Type	application/json

9. 保存标题值后，字符串将被星号替换，无法再次查看。

10. 这将自动保存 Webhook 详细信息。

添加秘密

在“秘密”字段中添加客户端秘密，以便在请求外部服务进行身份验证时一并传递：

• 以文本字符串形式输入密钥，如 purple unicorn。

• 最多使用 1 024 个字符。

• 请勿使用上下文变量。

外部服务负责检查和验证密文。 如果不需要标记，可指定任何字符串。 该字段不能为空。

要在输入密码时查看密码，请在输入前单击显示密码图标。 保存秘密后，星号将取代字符串，您将无法再次查看。

有关如何使用此字段的更多信息，请参阅 Webhook 安全性。

Webhook 安全性

通过验证随请求一起发送的 JSON 网络令牌（JWT）来验证 webhook 请求。 Webhook 微服务会自动生成 JWT，并在每次 Webhook 调用时通过 Authorization 标头发送：

• 对于新的网络钩子或通过编辑身份验证更新的网络钩子，授权标头将被忽略。

• 对于已保存身份验证标头的现有网络钩子，“编辑身份验证”选项被禁用。

• 更新现有 Webhook 以使用新的身份验证配置会改变其行为。

如果需要测试 JWT 验证，可以在外部服务中添加代码。 例如，如果在秘密字段中指定 purple unicorn，则可以使用以下代码：

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
}

为预处理配置网络钩子错误处理功能

如果 webhook 调用失败，您可以决定是否在预处理步骤中返回错误信息。 您有两个选择：

• 如果出现错误，继续处理用户输入，不更新 webhook：助手会忽略错误并处理信息而不更新 webhook 结果。 如果预处理有用但不是必须的，可以考虑这一选项。

• 如果 webhook 调用失败，则向客户端返回错误信息：如果在助手处理信息之前预处理至关重要，请选择此选项。

当您启用如果 webhook 调用失败则向客户端返回错误时，一切都会停止，直到预处理步骤成功完成。

定期测试外部流程，找出潜在故障。 如有必要，可调整此设置以防止信息处理中断。

测试 Webhook

在为生产环境中使用的助手启用网络钩子之前，请对其进行大量测试。

当有信息发送到您的助手进行处理时，就会触发 webhook。

排除网络钩子故障

以下错误代码可以帮助您找出可能遇到的问题的原因。 例如，如果您有一个网络聊天集成，如果您提交的每条测试消息都返回 There is an error with the message you just sent, but feel free to ask me something else 这样的消息，您就知道网络钩子出了问题。 如果显示此消息，请使用 cURL, 等 REST API 工具发送测试 /message API 请求，以便查看错误代码和返回的完整消息。

请求正文示例

了解预消息网络钩子请求体的格式非常有用，这样您的外部代码就可以处理它。

有效载荷包含 /message、有状态或无状态、第 2 版 API 请求的请求正文。 事件名称 message_received 表示该请求由预消息 Webhook 生成。 有关消息请求体的更多信息，请参阅 API 参考资料。

{
  "payload" : { Copy of request body sent to /message }
  "event": {
      "name": "message_received"
   }
}

跳过助理处理

消息前网络钩子的增强功能允许 Cloud Pak for Data- classic exerience 跳过消息处理，直接从网络钩子返回响应。 通过在网络钩子的 HTTP 响应中设置 x-watson-assistant-webhook-return 标头，可激活该功能。

响应主体

从 webhook 接收 POST 请求的服务必须返回一个 JSON 对象 (Accept: application/json)。

回复正文必须具有以下结构：

{
  "payload": {
    ...
  }
}

payload 必须包括请求正文中的 payload。 您的代码可以修改属性值或修改上下文变量，但返回的消息有效载荷必须遵循 message 方法模式。 更多信息，请参阅 API 参考。

示例 1

本例向您展示如何检查输入文本的语言，并将语言信息附加到输入文本字符串。

在预消息 webhook 配置页面中，可指定以下值：

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/check_language
• 秘密：无
• 标头名称：Content-Type
• 标头值：application/json

消息前网络钩子调用 IBM Cloud Functions 网络操作，操作名称为 check_language。

check_language 网页操作中的 node.js 代码如下。

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

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.text !== '') {
  // Send a request to the Watson Language Translator service to check the language of the input 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': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  json: true,
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["language"] = res.languages[0].language;
        console.log(JSON.stringify(params))
        //Append "in" plus "the language code" to the input text, surrounded by parentheses.
        const response = {
            body : {
                payload : {
                    input : {
                        text : params.payload.input.text + ' ' + '(in ' + res.languages[0].language + ')'
                    },
                },
            },
        };
        return response;
})
}
return {
    body : params
}
};

要测试网络钩子，请单击“预览”。 提交文本 Buenos días。 助手可能无法理解输入内容，因此会返回 Anything else 节点的响应。 不过，如果您进入助手的“分析”页面并打开“对话”，就可以看到提交的内容。 查看最近的用户对话。 日志显示用户输入为 Buenos días (in es)。 括号中的 es 代表西班牙语的语言代码，因此网络钩子成功识别出提交的文本是西班牙语短语。

示例 2

本例向您展示了如何检查收到的信息的语言，如果不是英语，则在提交给助手之前将其翻译成英语。

在 IBM Cloud Functions 中定义网络操作序列。 序列中的第一个操作是检查输入文本的语言。 序列中的第二个动作是将文本从原文翻译成英文。

在预消息 webhook 配置页面中，可指定以下值：

• URL: https://us-south.functions.appdomain.cloud/api/v1/web/e97d2516-5ce4-4fd9-9d05-acc3dd8ennn/default/translation_sequence
• 秘密：无
• 标头名称：Content-Type
• 标头值：application/json

序列中第一个网络操作的 node.js 代码如下：

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

function main(params) {
console.log(JSON.stringify(params))
if (params.payload.input.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': 'nnn'
       },
headers: {
    "Content-Type":"text/plain"
},
  body: [
          params.payload.input.text
  ],
  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 params
}
};

序列中的第二个网络操作将文本发送到 Watson Language Translator 服务，将输入文本从上一个网络操作中识别的语言翻译成英语。 翻译后的字符串会发送给您的助手，而不是原始文本。

序列中第二个操作的 node.js 代码如下：

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

function main(params) {
console.log(JSON.stringify(params))
//If the the incoming message is not null and is not English, translate it.
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'
       },
  headers: {
    "Content-Type":"application/json"
  },
       //The body includes the parameters that are required by the Language Translator service, the text to translate and the target language to translate it into.
  body: {
      text: [
          params.payload.input.text
          ],
          target: 'en'
  },
  json: true
};
     return rp(options)
    .then(res => {
        params.payload.context.skills["actions skill"].user_defined["original_input"] = params.payload.input.text;
        const response = {
            body : {
                payload : {
                    "context" : params.payload.context,
                    "input" : {
                        "text" : res.translations[0].translation,
                        "options" : {
                            "export" : true
                            }
                    },
                },
            },
        };
    return response
})
}
return {
    body : params
    }
};

在预览面板中测试网络钩子时，您可以提交 Buenos días，助手就会像您用英语说 Good morning 一样做出回应。 事实上，当您查看助手的“分析”页面并打开“对话”时，日志会显示用户输入的内容是 Good morning。

您可以添加一个信息后 webhook，在显示信息之前将信息回复翻译成客户的语言。 更多信息，请参见 示例 2。

示例 3

本示例展示了如何编写网络钩子响应，让 Cloud Pak for Data- classic experience 跳过信息处理，直接返回网络钩子的响应。

function main(params) {
  // Your custom logic to determine the response
  let responseText = "This response is directly from the pre-message webhook.";

  const response = {
    headers: {
      "X-Watson-Assistant-Webhook-Return": "true"
    },
    body: {
      output: {
        generic: [
          {
            response_type: "text",
            text: responseText
          }
        ]
      }
    }
  };

  return response;
}

删除网络钩子

1. 对于要配置的助手，单击 图标，然后选择设置。

2. 单击 Webhooks > Pre-message webhook。

3. 执行下列其中一个操作：

• 要停止调用 webhook 来处理每一条收到的信息，请将“信息前 webhook”开关设置为禁用。

• 要更改要调用的网络钩子，请单击删除网络钩子。