接收 Webhook 事件
更新时间不可用
了解云端转码中接收 Webhook 事件相关内容的适用场景、配置步骤、实现要点和注意事项。
本文仅适用于云端转码，不适用于观众端多码率。
Webhook 是一种基于 HTTP 协议的回调机制，允许服务端主动推送数据。声网的消息通知服务使用 Webhook 向你推送特定事件的通知，当你订阅的事件发生时，声网业务服务器会将事件消息发送给声网消息通知服务器，然后声网消息通知服务器会通过 HTTPS POST 请求将事件通知投递给你的服务器。消息通知服务已集成旁路推流、输入在线媒体流、云端录制、云端转码等业务下的一些事件。你可以向声网提供相关的配置信息来开通该服务。
前提条件
如果你的网络环境部署了防火墙，请将声网消息通知服务器的 IP 地址添加到白名单，以正常使用声网消息通知服务。详见查询消息通知服务器的 IP 地址。
用户配置
你需要联系技术支持开通消息通知服务，并提供以下配置信息：
-
接收消息通知的 HTTPS 服务器地址。
-
开通消息通知服务的项目所对应的 App ID。
-
你想使用通知服务的业务。
-
你想得到通知的事件。
-
选择是否开启消息通知重试。消息通知服务是实时通知，开启通知重试后，消息通知服务器就会在第一次通知失败后立即重试，再次发送消息通知，最多会尝试三次通知。消息通知服务器在以下任意一种情况下会认为通知失败：
- 发送消息通知后，10 秒内没有收到你的服务器的响应。
- 收到你的服务器响应的 HTTP 状态码不是 200。
配置消息通知服务后，你需要注意以下事项：
- 5 分钟后，该服务即会生效。你的服务器需要尽快响应消息通知服务器，响应的 Body 格式必须为 JSON。
- 声网系统将自动生成
secret。secret是字符串类型的密钥，可以用来生成签名，你需要保存这个密钥以备后续验签，详见验证签名。
消息通知回调格式
消息通知回调以 HTTPS POST 请求发送给你的服务器，请求的 Body 格式为 JSON。字符编码为 UTF-8。
消息通知回调的 Header 中包含以下字段：
| 字段名 | 值 |
|---|---|
Content-Type | application/json |
Agora-Signature | 声网用密钥（secret）和 HMAC/SHA1 算法生成的签名值。你需要使用密钥（secret）和 HMAC/SHA1 算法来验证该签名值。详见验证签名。 |
Agora-Signature-V2 | 声网用密钥（secret）和 HMAC/SHA256 算法生成的签名值。你需要使用密钥（secret）和 HMAC/SHA256 算法来验证该签名值。详见验证签名。 |
消息通知回调的 Body 中包含以下字段：
| 字段名 | 类型 | 含义 |
|---|---|---|
noticeId | String | 通知 ID，标识来自业务服务器的一次事件通知。 |
productId | Number | 业务 ID：3(Cloud Recording and Extension Service)，代表云端录制或云端转码服务。 |
eventType | Number | 通知的事件类型。 |
notifyMs | Number | 消息通知服务器向你的服务器发出回调请求的 Unix 时间戳，单位为毫秒。通知重试时会更新该时间。 |
payload | JSON Object | 事件内容。payload 字段是一个 JSON Object，包含事件的具体内容。详细字段见 Payload 说明。 |
验证签名
为提高声网消息服务器和你的服务器之间的通信安全，你可以通过签名机制进行身份验证，确保接收到的请求来自声网。
当声网向你的服务器发送消息通知回调时，会使用密钥通过 HMAC/SHA1 和 HMAC/SHA256 算法生成签名值，并分别添加在 HTTPS 请求 Header 的 Agora-Signature 和 Agora-Signature-V2 字段中。
参考以下步骤进行签名验证：
-
获取密钥：配置声网消息通知服务时，声网会生成一个密钥。在控制台左侧导航栏的全部产品 > 拓展能力 > 媒体服务下，选择云端转码，进入功能配置子页面，然后在 Webhook 页签点击复制按钮即可获取该密钥。
-
收到回调后，使用密钥和请求 Body 中的参数，选用 HMAC/SHA1 或 HMAC/SHA256 算法计算签名值。
-
将你计算出的签名与请求 Header 中对应的字段进行对比：
- 如果你选用 HMAC/SHA1 算法：将计算值与
Agora-Signature字段对比。二者完全相同则说明该请求是由声网发送的。 - 如果你选用 HMAC/SHA256 算法：将计算值与
Agora-Signature-V2字段对比。二者完全相同则说明该请求是由声网发送的。
- 如果你选用 HMAC/SHA1 算法：将计算值与
声网提供多种语言的验证签名示例代码供你参考。
注意事项
- 你的服务器收到的通知顺序和事件发生的顺序不一定完全一致。
- 为确保消息通知的可靠性，每次事件可能会有不止一次消息通知，你的服务器需要能处理重复消息。