接收 Webhook 事件

Webhook 是一种基于 HTTP 协议的回调机制，允许服务端主动推送数据。

声网的消息通知服务使用 Webhook 向你推送特定事件的通知，当你订阅的事件发生时，声网业务服务器会将事件消息发送给声网消息通知服务器，然后声网消息通知服务器会通过 HTTPS POST 请求将事件通知投递给你的服务器。

适用场景Copy Anchor Link

声网消息通知服务具有低延时、高并发、稳定可靠的特点。对于对话式 AI 引擎，在智能体高并发的场景下，通过消息通知服务可以在业务层维护一个实时同步的智能体状态机，实现以下功能：

• 实时监听智能体加入或离开频道事件。
• 实时监听智能体错误事件。

前提条件Copy Anchor Link

开始之前，请确保你满足以下条件：

• 有效的声网开发者账号和声网控制台项目。详见开通服务。
• 满足以下条件的服务器：
  • 支持 HTTPS 协议。为提高安全性，声网消息通知服务不再支持 HTTP 服务器地址。
  • （推荐）支持 HTTPS 连接重用，即 keep-alive 模式，以降低消息投递延时。声网建议进行如下设置：
    • MaxKeepAliveRequests：大于等于 100。
    • KeepAliveTimeout：大于等于 10 秒。

开通消息通知服务Copy Anchor Link

使用消息通知服务前，你需要在声网控制台自助开通并填写配置信息。

1. 启用并配置服务Copy Anchor Link

参考以下步骤开通并配置消息通知服务：

1. 登录声网控制台，点击左侧导航栏的全部产品，选择对话式 AI 引擎。

2. 在产品页面，点击进入 Webhook 页签。

3. 在配置区域点击新增事件，然后在新建 Webhook 弹出框中填入以下信息，最后点击保存。

   • 消息接收区域：你的消息通知接收服务器所在的区域。声网会根据你提供的区域就近接入声网节点服务器。
   • 消息接收 URL：接收消息通知的 HTTPS 服务器地址。
   • 订阅事件：需要订阅的事件。详见对话式 AI 引擎事件类型。如需配置 QPS（每秒请求数）较高的事件，请确保你的服务器有足够的处理能力。建议一次选择所有需要订阅的事件，以避免多次配置和健康检查。
   • IP 白名单：如果你的消息接收服务器受防火墙限制，请勾选该选项，并按照以下说明将声网消息通知服务器的 IP 地址全部添加到防火墙白名单。

完成功能配置后，声网会对你的配置进行健康检查。

2. 完成健康检查Copy Anchor Link

健康检查的步骤如下：

1. 声网会根据你订阅的事件生成对应的测试事件，并向你的服务器发送事件回调。在测试事件回调中，channelName 为 test_webhook，uid 为 12121212。

2. 接收到每个测试事件回调后，你的服务器需要在 10 秒内对声网消息服务器作出响应，响应状态码必须为 200，响应包体格式为 JSON，包体内容不作要求。示例代码如下：

   Copy Text

   const express = require('express');
   const app = express();
   const bodyParser = require('body-parser');
   
   // 使用 body-parser 中间件解析请求体
   app.use(bodyParser.json());
   
   // 处理接收到的 POST 请求
   app.post('/', express.json({ type: 'application/json' }), (req, res) => {
       const event = request.body;
       // 5 秒后发送响应
       setTimeout(() => {
           res.status(200).json({message: 'Success'});
       }, 5000);
       // 发送响应后，再执行耗时较长的任务
   });

3. 如果健康检查失败，请根据声网控制台的提示进行错误排查。常见的错误包括：

   • 请求超时：你的服务器没有在 10 秒内返回 200。请检查你的服务器是否及时对事件回调作出正确的响应。如果响应正确，请联系技术支持确认声网消息通知服务器到你的服务器之间的网络连接是否正常。
   • 证书错误：HTTPS 证书错误。请检查证书是否正确。如果你的服务器受防火墙限制，请检查是否已将声网消息通知服务器的 IP 地址全部添加到防火墙白名单。
   • 域名不可达：域名不合法，无法解析到目标 IP 地址。请检查你的服务器部署是否正确。
   • 响应错误：你的服务器返回的响应状态码不为 200，具体的状态码和描述详见控制台提示。

4. 健康检查成功后，点击保存配置。

配置通过审核后，消息通知服务的状态会显示已启用。

接收消息通知回调Copy Anchor Link

成功开通声网消息通知服务后，当订阅的频道事件发生时，声网消息服务器会以 HTTPS POST 请求的形式向你的服务器发送消息通知回调。详见对话式 AI 引擎事件类型。

响应要求Copy Anchor Link

接收到消息通知回调后，你的服务器需要在 10 秒内对声网消息服务器作出响应。响应包体格式为 JSON，包体内容不作要求。

声网消息服务器发送通知后的 10 秒内，如果没有收到你的服务器的响应或响应状态码不是 200，会认为消息通知失败。失败后，声网消息通知服务器会立即重新发送消息通知，投递间隔随着重试次数的上升逐渐增加，直到重试三次后停止投递。

验证签名Copy Anchor Link

为提高声网消息服务器和你的服务器之间的通信安全，你可以通过签名机制进行身份验证，确保接收到的请求来自声网。

当声网向你的服务器发送消息通知回调时，会使用密钥通过 HMAC/SHA1 和 HMAC/SHA256 算法生成签名值，并分别添加在 HTTPS 请求 Header 的 Agora-Signature 和 Agora-Signature-V2 字段中。

参考以下步骤进行签名验证：

1. 获取密钥：配置声网消息通知服务时，声网会生成一个密钥。在控制台左侧导航栏的全部产品下选择对话式 AI 引擎，进入 Webhook 页签点击复制按钮即可获取该密钥。

2. 收到回调后，使用密钥和请求包体里的参数，选用 HMAC/SHA1 或 HMAC/SHA256 算法计算签名值。

3. 将你计算出的签名与请求 Header 中对应的字段进行对比：

   • 如果你选用 HMAC/SHA1 算法：将计算值与 Agora-Signature 字段对比。二者完全相同则说明该请求是由声网发送的。
   • 如果你选用 HMAC/SHA256 算法：将计算值与 Agora-Signature-V2 字段对比。二者完全相同则说明该请求是由声网发送的。

声网提供多种语言的验证签名示例代码供你参考。

开发注意事项Copy Anchor Link

• 声网消息通知服务不保证消息通知完全按照事件发生的顺序到达，你的服务器需要能处理乱序消息。
• 为提高消息服务的可靠性，每次事件可能会有不止一次消息通知，你的服务器需要能处理重复消息。