跳到主要内容

卡片按钮回调

当 actionType="api" 的卡片按钮被触发时,TWT Link 向按钮 action 配置的 URL 发送一次 HTTP POST。本页只说明应用后端接收回调和返回响应的规则。

POST 请求​

项目规则
请求方式POST
Content-Typeapplication/json
X-Link-Timestamp十进制 Unix 时间戳字符串,单位为毫秒
X-Link-Signature使用当前应用 App Secret 计算的 HMAC-SHA256,结果使用标准 Base64 编码

请求正文是 JSON 对象,只包含以下三个字符串字段:

{"msgId":"message-id-xxx","userId":"10001","value":"approve:REQ-1001"}
字段类型说明
msgIdstring被触发卡片消息的服务端消息 ID
userIdstring触发按钮的用户 ID
valuestring发送卡片时配置的按钮参数;未配置或为 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,才视为回调成功。

响应字段​

字段类型必填说明
codeinteger是业务结果码:数字 0 表示成功,其他整数表示失败;字符串 "0" 无效
msgstring / 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 字节)失败,正文不解析,截断内容不作为错误说明或业务数据
网络错误或超时失败

错误说明按以下规则选择:

  1. 正文符合响应结构时,优先使用非空 msg。
  2. 正文不符合响应结构时,使用去除首尾空白后的非空原始正文;不会单独提取 message 或 error 等其他字段。
  3. 无可用正文说明且 HTTP 非 2xx 时,使用 HTTP 状态文本,例如 502 Bad Gateway;超限响应也只按 HTTP 状态选择说明。

3xx 不跟随重定向。单次回调总预算为 3 秒,包含响应正文读取;应用后端应在此时间内完成验签及必要的业务落库或可靠入队,并返回完整的 JSON 响应。