卡片按鈕回呼
當 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 回應。