Webhook 回调事件

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

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

适用场景Copy Anchor Link

互动白板的消息通知服务可以在业务层维护一个实时同步的状态机，实现实时监听文档转换任务的进度和运行状态信息。

前提条件Copy Anchor Link

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

• 已开启文档转换服务并配置第三方云存储的有效声网项目。详见使用文档转换服务。
• 满足以下条件的服务器：
  • 支持 HTTPS 协议。为提高安全性，声网消息通知服务不再支持 HTTP 服务器地址。
  • （推荐）支持 HTTPS 连接重用，即 keep-alive 模式，以降低消息投递延时。声网建议进行如下设置：
    • MaxKeepAliveRequests：大于等于 100。
    • KeepAliveTimeout：大于等于 10 秒。

启用文档转换 Webhook 回调Copy Anchor Link

调用发起文档转换时，在请求包体中的 webhookEndpoint 字段传入 Webhook 回调地址即可对本次转换启用文档转换 Webhook 回调，接收来自服务端的文档转换进度和运行状态信息，回调内容和字段解释详见 Webhook 回调内容。

curl --request POST \
  --url https://api.netless.link/v5/projector/tasks \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'region: cn-hz' \
  --header 'token: NETLESSSDK_YWs9xxxxxxM2MjRi' \
  --data '{
  "resource": "https://docs-test-xx.oss-cn-hangzhou.aliyuncs.com/xxx",
  "type": "dynamic",
  "preview": true,
  # 配置 Webhook 回调地址
  "webhookEndpoint": "https://example.com/agoracallback",
  # 配置 Webhook 回调失败时的重试次数
  "webhookRetry": 3,
  "imageCompressionLevel": 0
}'

转换任务完成时，声网消息服务器会以 HTTPS POST 请求的形式向你的服务器发送消息通知回调。数据格式为 JSON，字符编码为 UTF-8，签名算法为 HMAC/SHA1 或 HMAC/SHA256。

验证签名Copy Anchor Link

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

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

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

1. 获取密钥：登录控制台，在互动白板-功能配置页面点击生成 webhook 密钥为你的项目生成一个文档转换 Webhook 密钥。

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

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

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

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

参考信息Copy Anchor Link

开发注意事项Copy Anchor Link

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

Webhook 回调内容Copy Anchor Link

请求 HeaderCopy Anchor Link

消息通知回调的请求 Header 包含以下字段：

请求 BodyCopy Anchor Link

消息通知回调的请求 Body 包含以下字段：

data 包含以下字段：

• taskId：String。转换任务的 UUID，即转换任务的唯一标识符。
• taskType：转换任务类型，取值如下：
  • dynamic_convert：动态文档转换，即文档转网页。
  • static_convert：静态文档转换，即文档转图片。
• prefixUrl：String。转换结果文件地址前缀路径。
• pageCount：Number。文档页数，转换任务失败时没有该字段。
• previews：JSON Object。转换后的文档预览图地址，每页对应一个预览图地址。该参数仅在发起文档转换时，请求 Body 中的 preview 设为 true ，且 type 设为 dynamic 时才生效。
• images：JSON Object。文档转图片结果的地址和图片参数，每页对应一张图片。该参数仅在调用发起文档转换时，请求 Body 中的 type 设为 static 时生效。
  • width：Number。图片宽度 (px)。
  • height：Number。图片高度 (px)。
  • url：String。图片链接地址。
• note：String。从文档中提取出的所有备注内容。
• noticeTimestamp：Number。发送请求的时间戳。

以下为请求包体示例：

{
    "code": 0,
    "message": "ok",
    "data": {
        "taskId": "0d2c7604b730xxxxxxxxx1e31d344c",
        "taskType": "dynamic_convert",
        "pageCount": 5,
        "previews": {
            "1": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert/0d2c7604b730xxxxxxxxx1e31d344c/preview/1.png",
            "2": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert/0d2c7604b730xxxxxxxxx1e31d344c/preview/2.png",
            "3": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert/0d2c7604b730xxxxxxxxx1e31d344c/preview/3.png",
            "4": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert/0d2c7604b730xxxxxxxxx1e31d344c/preview/4.png",
            "5": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert/0d2c7604b730xxxxxxxxx1e31d344c/preview/5.png"
        },
        "note": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert/0d2c7604b730xxxxxxxxx1e31d344c/jsonOutput/note.json",
        "prefix": "https://conversion-demo-cn.oss-cn-hangzhou.aliyuncs.com/demo/dynamicConvert",
        "noticeTimestamp": 1724322571541
    }
}

相关文档Copy Anchor Link

• 使用文档转换服务
• 发起文档转换
• 查询转换任务进度