2024/09/03 23:13:25
接收 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 字段说明。 |
验证签名
声网系统直接生成了密钥 (secret
),并通过 HMAC/SHA1 和 HMAC/SHA256 算法最终生成 Agora-Signature
和 Agora-Signature-V2
签名。
你可以使用已保存的密钥 (secret
),选用 HMAC/SHA1 或 HMAC/SHA256 算法计算签名值,以验证 Agora-Signature
或 Agora-Signature-V2
。
验证签名时你可以参考以下代码:
Python 示例
- HMAC/SHA1
- HMAC/SHA256
Python
#!/usr/bin/env python2
# !-*- coding: utf-8 -*-
import hashlib
import hmac
# 拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 request_body 是反序列化之前的 binary byte array,不是反序列化之后的 dictionary
request_body = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
secret = 'secret'
signature = hmac.new(secret, request_body, hashlib.sha1).hexdigest()
print(signature) # 033c62f40f687675f17f0f41f91a40c71c0f134c
Python
#!/usr/bin/env python2
# !-*- coding: utf-8 -*-
import hashlib
import hmac
# 拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 request_body 是反序列化之前的 binary byte array,不是反序列化之后的 dictionary
request_body = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
secret = 'secret'
signature2 = hmac.new(secret, request_body, hashlib.sha256).hexdigest()
print(signature2) # 6d3320c60b11101395b7fc8f9068748808a0aa1bfa064438e39d1bc2c7d74d99
Node.js 示例
- HMAC/SHA1
- HMAC/SHA256
JavaScript
const crypto = require('crypto')
// 拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 requestBody 是反序列化之前的 binary byte array,不是反序列化之后的 object
const requestBody = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
const secret = 'secret'
const signature = crypto.createHmac('sha1', secret).update(requestBody, 'utf8').digest('hex')
console.log(signature) // 033c62f40f687675f17f0f41f91a40c71c0f134c
JavaScript
const crypto = require('crypto')
// 拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 requestBody 是反序列化之前的 binary byte array,不是反序列化之后的 object
const requestBody = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}'
const secret = 'secret'
const signature2 = crypto.createHmac('sha256', secret).update(requestBody, 'utf8').digest('hex')
console.log(signature2) // 6d3320c60b11101395b7fc8f9068748808a0aa1bfa064438e39d1bc2c7d74d99
Java 示例
- HMAC/SHA1
- HMAC/SHA256
Java
import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
public class HmacSha {
// 将加密后的字节数组转换成字符串
public static String bytesToHex(byte[] bytes) {
StringBuffer sb = new StringBuffer();
for (int i = 0; i < bytes.length; i++) {
String hex = Integer.toHexString(bytes[i] & 0xFF);
if (hex.length() < 2) {
sb.append(0);
}
sb.append(hex);
}
return sb.toString();
}
// HMAC/SHA1 加密,返回加密后的字符串
public static String hmacSha1(String message, String secret) {
try {
SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(
"utf-8"), "HmacSHA1");
Mac mac = Mac.getInstance("HmacSHA1");
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(message.getBytes("utf-8"));
return bytesToHex(rawHmac);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
public static void main(String[] args) {
//拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 request_body 是反序列化之前的 binary byte array,不是反序列化之后的 object
String request_body = "{\"eventMs\":1560408533119,\"eventType\":10,\"noticeId\":\"4eb720f0-8da7-11e9-a43e-53f411c2761f\",\"notifyMs\":1560408533119,\"payload\":{\"a\":\"1\",\"b\":2},\"productId\":1}";
String secret = "secret";
System.out.println(hmacSha1(request_body, secret)); //033c62f40f687675f17f0f41f91a40c71c0f134c
}
}
Java
import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
public class HmacSha {
// 将加密后的字节数组转换成字符串
public static String bytesToHex(byte[] bytes) {
StringBuffer sb = new StringBuffer();
for (int i = 0; i < bytes.length; i++) {
String hex = Integer.toHexString(bytes[i] & 0xFF);
if (hex.length() < 2) {
sb.append(0);
}
sb.append(hex);
}
return sb.toString();
}
// HMAC/SHA256 加密,返回加密后的字符串
public static String hmacSha256(String message, String secret) {
try {
SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(
"utf-8"), "HmacSHA256");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(signingKey);
byte[] rawHmac = mac.doFinal(message.getBytes("utf-8"));
return bytesToHex(rawHmac);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
public static void main(String[] args) {
//拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 request_body 是反序列化之前的 binary byte array,不是反序列化之后的 object
String request_body = "{\"eventMs\":1560408533119,\"eventType\":10,\"noticeId\":\"4eb720f0-8da7-11e9-a43e-53f411c2761f\",\"notifyMs\":1560408533119,\"payload\":{\"a\":\"1\",\"b\":2},\"productId\":1}";
String secret = "secret";
System.out.println(hmacSha256(request_body, secret)); //033c62f40f687675f17f0f41f91a40c71c0f134c
}
}
PHP 示例
- HMAC/SHA1
- HMAC/SHA256
PHP
<?php
function assertEqual($expect, $actual)
{
if ($expect != $actual) {
echo("\n assert failed");
echo("\n expect:\n " . $expect);
echo("\n actual:\n " . $actual);
echo("\n");
} else {
echo("assert ok\n");
echo("\n");
}
}
// 拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 requestBody 是反序列化之前的 binary byte array,不是反序列化之后的 object
$request_body = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}';
$secret = 'secret';
// 请求 header 中 Agora-Signature 的值
$sha1 = '033c62f40f687675f17f0f41f91a40c71c0f134c';
$res1 = (hash_hmac('sha1', $request_body, $secret));
assertEqual($res1, $sha1);
?>
PHP
<?php
function assertEqual($expect, $actual)
{
if ($expect != $actual) {
echo("\n assert failed");
echo("\n expect:\n " . $expect);
echo("\n actual:\n " . $actual);
echo("\n");
} else {
echo("assert ok\n");
echo("\n");
}
}
// 拿到消息通知的 raw request body 并对其计算签名,也就是说下面代码中的 requestBody 是反序列化之前的 binary byte array,不是反序列化之后的 object
$request_body = '{"eventMs":1560408533119,"eventType":10,"noticeId":"4eb720f0-8da7-11e9-a43e-53f411c2761f","notifyMs":1560408533119,"payload":{"a":"1","b":2},"productId":1}';
$secret = 'secret';
// 请求 header 中 Agora-Signature-V2 的值
$sha256 = '6d3320c60b11101395b7fc8f9068748808a0aa1bfa064438e39d1bc2c7d74d99';
$res2 = (hash_hmac('sha256', $request_body, $secret));
assertEqual($res2, $sha256);
?>
注意事项
- 你的服务器收到的通知顺序和事件发生的顺序不一定完全一致。
- 为确保消息通知的可靠性,每次事件可能会有不止一次消息通知,你的服务器需要能处理重复消息。