用户拉黑通知回调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 字符串
  1. 按下方公式构造 StringToSign,拼接时不添加分隔符或换行。
  2. 对 StringToSign 的 UTF-8 字节计算 MD5,将摘要转换为 32 位小写十六进制字符串。
  3. 将结果与请求头中的 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 次尝试。

接收方应及时返回响应,并做好重复通知处理,避免同一用户被重复执行业务操作。