用户处罚回调API

接收用户禁言、封号等处罚通知。

POSTcallbackUrl

在控制台「服务配置 → 用户处罚 → 回调 URL」配置接收地址。

请求参数

请求头

以下请求头均为必需。

Header	值	说明
`Content-Type`	`application/json; charset=UTF-8`	请求体格式
`Accept`	`application/json; charset=UTF-8`	响应格式
`X-AppId`	—	控制台「服务配置」中的项目编号
`X-TimeStamp`	—	回调发起时的 UTC 时间，采用 W3C 格式。格式示例：`2026-09-30T02:30:00Z`，仅用于说明格式。
`Authorization`	—	签名值，计算方式见下文「回调签名」

请求体

参数	类型	必需	说明
`appId`	`String`	必需	项目编号
`userId`	`String`	必需	用户ID
`type`	`String`	必需	处罚方式（mute：禁言，ban_account：封号）
`hours`	`String`	必需	处罚时长（permanent：永久，{n}：{n}小时）
`category`	`String`	必需	处罚原因（sensitive：敏感词，advertising：广告词）

请求示例

{
  "appId": "80700001",
  "userId": "usertest",
  "type": "mute",
  "hours": "24",
  "category": "advertising"
}

回调签名

按以下规则验证 Authorization。本回调将完整 CallbackUrl 加入签名，不使用请求接口中分开的主机名与路径。

签名参数	值
`HTTPMethod`	`POST`
`CallbackUrl`	控制台配置的完整回调 URL

对 UTF-8 编码的请求体计算 SHA256，并将摘要转为十六进制字符串。
按下方规则构造 StringToSign。
使用 secretKey 计算 HMAC-SHA256，将结果转为 Base64 后，与 Authorization 比较。

CanonicalizedQueryString = hex(sha256(jsonBody))
StringToSign = HTTPMethod + "\n" +
               CallbackUrl + "\n" +
               CanonicalizedQueryString + "\n" +
               "X-AppId:" + SAME_APPID_IN_HEADER + "\n" +
               "X-TimeStamp:" + SAME_TIMESTAMP_IN_HEADER