用户拉黑通知回调API
更新时间:
接收广告刷屏、多会话广告等规则触发的用户自动拉黑通知。
POSTcallbackUrl
在控制台「服务配置 → 审核系统回调地址 → 用户拉黑通知回调」配置接收地址。回调 URL 中请勿使用 secretKey、appId、taskId 作为自定义查询参数名。
请求参数
请求头
以下请求头均为必需。
Header
值
说明
Content-Type
application/json
请求体格式
Accept
application/json;charset=UTF-8
响应格式
signature
—
MD5 签名值,32 位小写十六进制字符串,计算方式见下文「回调签名」
请求体
参数
类型
必需
说明
result
String
必需
拉黑数据的 JSON 字符串
解析请求体获取 result 字符串,验签通过后,再将其解析为以下业务对象。
result 业务字段
参数
类型
必需
说明
appId
String
必需
项目编号
userIds
Array<String>
必需
被拉黑用户ID列表
type
Number
必需
拉黑类型:2 表示广告刷屏,5 表示多会话广告
userId
String
非必需
被拉黑用户ID;可能不传,建议统一从 userIds 获取用户
ruleId
Number
必需
刷屏规则ID;0 表示未指定规则或使用默认规则
channel
Number
必需
拉黑来源:2 表示广告刷屏,5 表示多会话广告
expirationTime
Number
必需
拉黑到期时间,Unix 毫秒时间戳;0 表示未指定到期时间
请求示例
广告刷屏
{
"result": "{\"appId\":\"80700001\",\"userIds\":[\"usertest\"],\"type\":2,\"userId\":\"usertest\",\"ruleId\":1,\"channel\":2,\"expirationTime\":0}"
}
解析 result 后得到:
{
"appId": "80700001",
"userIds": ["usertest"],
"type": 2,
"userId": "usertest",
"ruleId": 1,
"channel": 2,
"expirationTime": 0
}
多会话广告
{
"result": "{\"appId\":\"80700001\",\"userIds\":[\"usertest\"],\"type\":5,\"ruleId\":0,\"channel\":5,\"expirationTime\":0}"
}
回调签名
按以下规则验证请求头中的 signature。
签名参数
值
secretKey
控制台「服务配置 → 审核系统回调地址」中的 Callback Key
result
请求体解析后得到的原始 result 字符串
- 按下方公式构造
StringToSign,拼接时不添加分隔符或换行。
- 对
StringToSign 的 UTF-8 字节计算 MD5,将摘要转换为 32 位小写十六进制字符串。
- 将结果与请求头中的
signature 比较。
StringToSign = "appIdnullresult" + result + "taskIdnull" + secretKey
signature = lowercase_hex(MD5(UTF8(StringToSign)))
公式中的 appIdnullresult 和 taskIdnull 均为固定文本,不需要替换其中的 null。验签使用原始 result 字符串,保持字段顺序、空格等内容不变,不要重新序列化业务对象后计算签名。
签名示例
使用上方「广告刷屏」示例的原始 result 字符串,假设密钥为 example-key,签名原文为一行:
appIdnullresult{"appId":"80700001","userIds":["usertest"],"type":2,"userId":"usertest","ruleId":1,"channel":2,"expirationTime":0}taskIdnullexample-key
得到的签名值为:
signature: 957c7b92d0c09e8d3ebecf232ec61c29
回调响应及重试
接收方处理完成后应返回 HTTP 200。HTTP 2xx 状态码表示接收成功,响应体中的业务字段不参与回调成功判断。可返回:
{"code": 0}
收到非 2xx HTTP 响应时,系统最多额外重试 3 次,加上首次请求共最多 4 次尝试。
接收方应及时返回响应,并做好重复通知处理,避免同一用户被重复执行业务操作。
接收广告刷屏、多会话广告等规则触发的用户自动拉黑通知。
POST
callbackUrl在控制台「服务配置 → 审核系统回调地址 → 用户拉黑通知回调」配置接收地址。回调 URL 中请勿使用 secretKey、appId、taskId 作为自定义查询参数名。
请求参数
请求头
以下请求头均为必需。
| Header | 值 | 说明 |
|---|---|---|
Content-Type |
application/json |
请求体格式 |
Accept |
application/json;charset=UTF-8 |
响应格式 |
signature |
— | MD5 签名值,32 位小写十六进制字符串,计算方式见下文「回调签名」 |
请求体
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
result |
String |
必需 | 拉黑数据的 JSON 字符串 |
解析请求体获取 result 字符串,验签通过后,再将其解析为以下业务对象。
result 业务字段
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
appId |
String |
必需 | 项目编号 |
userIds |
Array<String> |
必需 | 被拉黑用户ID列表 |
type |
Number |
必需 | 拉黑类型:2 表示广告刷屏,5 表示多会话广告 |
userId |
String |
非必需 | 被拉黑用户ID;可能不传,建议统一从 userIds 获取用户 |
ruleId |
Number |
必需 | 刷屏规则ID;0 表示未指定规则或使用默认规则 |
channel |
Number |
必需 | 拉黑来源:2 表示广告刷屏,5 表示多会话广告 |
expirationTime |
Number |
必需 | 拉黑到期时间,Unix 毫秒时间戳;0 表示未指定到期时间 |
请求示例
广告刷屏
{
"result": "{\"appId\":\"80700001\",\"userIds\":[\"usertest\"],\"type\":2,\"userId\":\"usertest\",\"ruleId\":1,\"channel\":2,\"expirationTime\":0}"
}
解析 result 后得到:
{
"appId": "80700001",
"userIds": ["usertest"],
"type": 2,
"userId": "usertest",
"ruleId": 1,
"channel": 2,
"expirationTime": 0
}
多会话广告
{
"result": "{\"appId\":\"80700001\",\"userIds\":[\"usertest\"],\"type\":5,\"ruleId\":0,\"channel\":5,\"expirationTime\":0}"
}
回调签名
按以下规则验证请求头中的 signature。
| 签名参数 | 值 |
|---|---|
secretKey |
控制台「服务配置 → 审核系统回调地址」中的 Callback Key |
result |
请求体解析后得到的原始 result 字符串 |
- 按下方公式构造
StringToSign,拼接时不添加分隔符或换行。 - 对
StringToSign的 UTF-8 字节计算 MD5,将摘要转换为 32 位小写十六进制字符串。 - 将结果与请求头中的
signature比较。
StringToSign = "appIdnullresult" + result + "taskIdnull" + secretKey
signature = lowercase_hex(MD5(UTF8(StringToSign)))
公式中的 appIdnullresult 和 taskIdnull 均为固定文本,不需要替换其中的 null。验签使用原始 result 字符串,保持字段顺序、空格等内容不变,不要重新序列化业务对象后计算签名。
签名示例
使用上方「广告刷屏」示例的原始 result 字符串,假设密钥为 example-key,签名原文为一行:
appIdnullresult{"appId":"80700001","userIds":["usertest"],"type":2,"userId":"usertest","ruleId":1,"channel":2,"expirationTime":0}taskIdnullexample-key
得到的签名值为:
signature: 957c7b92d0c09e8d3ebecf232ec61c29
回调响应及重试
接收方处理完成后应返回 HTTP 200。HTTP 2xx 状态码表示接收成功,响应体中的业务字段不参与回调成功判断。可返回:
{"code": 0}
收到非 2xx HTTP 响应时,系统最多额外重试 3 次,加上首次请求共最多 4 次尝试。
接收方应及时返回响应,并做好重复通知处理,避免同一用户被重复执行业务操作。