卡片按钮回调
当 actionType="api" 的卡片按钮被触发时,TWT Link 向按钮 action 配置的 URL 发送一次 HTTP POST。本页只说明应用后端接收回调和返回响应的规则。
POST 请求
| 项目 | 规则 |
|---|---|
| 请求方式 | POST |
Content-Type | application/json |
X-Link-Timestamp | 十进制 Unix 时间戳字符串,单位为毫秒 |
X-Link-Signature | 使用当前应用 App Secret 计算的 HMAC-SHA256,结果使用标准 Base64 编码 |
请求正文是 JSON 对象,只包含以下三个字符串字段:
{"msgId":"message-id-xxx","userId":"10001","value":"approve:REQ-1001"}
| 字段 | 类型 | 说明 |
|---|---|---|
msgId | string | 被触发卡片消息的服务端消息 ID |
userId | string | 触发按钮的用户 ID |
value | string | 发送卡片时配置的按钮参数;未配置或为 null 时为空字符串 |
正文不包含按钮序号、robotCode、App Secret 或其他客户端字段。value 是发送卡片时保存的字符串,后端不要把它当作客户端临时提交的 JSON 对象。
签名算法
回调正文保持 JSON 原始字节,平台不对正文做 AES 加密;应用后端使用 HMAC-SHA256 验证来源和正文完整性,传输保密由 HTTPS 提供。
signingInput = X-Link-Timestamp + "\n" + rawBody
signature = Base64(HMAC-SHA256(AppSecret, signingInput))
| 项目 | 固定规则 |
|---|---|
| 密钥 | 发送应用当前 App Secret 的 UTF-8 字节;直接使用完整文本,不做 Base64 解码或预先哈希,不使用 access_token |
| 时间戳 | 使用 X-Link-Timestamp 的原始十进制字符串,不要转换后再拼接 |
| 拼接 | 时间戳 UTF-8 字节 + 一个换行字节 0x0A + 原始 HTTP body 字节;不是两个字符 \n,也不是 CRLF |
| 输出 | 将 32 字节 HMAC 结果做标准 Base64 编码,保留 = 填充;不是十六进制或 Base64URL |
| 比较 | 将 X-Link-Signature 做 Base64 解码后,使用恒定时间比较 |
验签必须在 JSON 解析前保留原始 body。空格、转义、字段顺序或换行变化都会导致签名不同。验签通过后,再解析并校验 msgId、userId 和 value。
Node.js 验签示例
import { createHmac, timingSafeEqual } from "node:crypto";
/** 验证卡片回调的原始正文签名;调用方应在解析 JSON 前传入 rawBody。 */
function verifyCardAction(rawBody, timestamp, signature, appSecret) {
if (!Buffer.isBuffer(rawBody) || typeof timestamp !== "string"
|| !/^\d+$/.test(timestamp) || typeof signature !== "string"
|| typeof appSecret !== "string" || !appSecret) {
return false;
}
const expected = createHmac("sha256", appSecret)
.update(timestamp + "\n", "utf8")
.update(rawBody)
.digest();
const received = Buffer.from(signature, "base64");
// 先检查长度,再恒定时间比较,避免普通字符串比较泄露签名信息。
return received.length === expected.length && timingSafeEqual(received, expected);
}
返回值约束
应用后端完成验签和业务处理后,应以 Content-Type: application/json 返回 JSON 对象。只有 HTTP 状态码为 2xx,且响应正文中的 code 为数字 0,才视为回调成功。
响应字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | integer | 是 | 业务结果码:数字 0 表示成功,其他整数表示失败;字符串 "0" 无效 |
msg | string / null | 否 | 处理结果说明;首尾空白会被去除,缺失、null 或全空白时按空字符串处理;成功时保留空字符串,失败时按下文规则选择错误说明 |
data | 任意 JSON 值 | 否 | 业务数据,可为对象、数组、字符串、数字、布尔值或 null;缺失时按 null 处理;响应结构有效时,成功和失败都会保留该字段的 JSON 值 |
成功示例
返回 HTTP 200 OK:
{
"code": 0,
"msg": "处理成功",
"data": {
"requestId": "REQ-1001",
"status": "approved"
}
}
不需要结果说明或业务数据时,最小成功正文为 {"code":0}。
业务失败示例
返回 HTTP 200 OK,并通过非零 code 表达业务失败:
{
"code": 1,
"msg": "该申请已处理",
"data": {
"requestId": "REQ-1001",
"status": "already_processed"
}
}
状态与异常处理
| 响应情况 | 判定 |
|---|---|
HTTP 2xx,正文为有效响应对象,code: 0 | 成功,保留 msg 和 data |
HTTP 2xx,正文为有效响应对象,code 非零 | 业务失败,保留 data,并选择错误说明 |
HTTP 非 2xx | 失败,即使正文中的 code 为 0;响应结构有效时仍保留 data |
空正文、非 JSON 对象、缺少 code、字符串 code 或非字符串且非 null 的 msg | 失败;204 No Content 也属于空正文失败 |
| 响应正文超过 64 KiB(65,536 字节) | 失败,正文不解析,截断内容不作为错误说明或业务数据 |
| 网络错误或超时 | 失败 |
错误说明按以下规则选择:
- 正文符合响应结构时,优先使用非空
msg。 - 正文不符合响应结构时,使用去除首尾空白后的非空原始正文;不会单独提取
message或error等其他字段。 - 无可用正文说明且 HTTP 非
2xx时,使用 HTTP 状态文本,例如502 Bad Gateway;超限响应也只按 HTTP 状态选择说明。
3xx 不跟随重定向。单次回调总预算为 3 秒,包含响应正文读取;应用后端应在此时间内完成验签及必要的业务落库或可靠入队,并返回完整的 JSON 响应。