Card Button Callback
When an actionType="api" card button is triggered, TWT Link sends one HTTP POST to the URL configured in the button's action. This page covers only the application backend's callback request and response rules.
POST request
| Item | Rule |
|---|---|
| Method | POST |
Content-Type | application/json |
X-Link-Timestamp | Decimal Unix timestamp string in milliseconds |
X-Link-Signature | HMAC-SHA256 computed with the current App Secret, encoded with standard Base64 |
The request body is a JSON object containing only these three string fields:
{"msgId":"message-id-xxx","userId":"10001","value":"approve:REQ-1001"}
| Field | Type | Description |
|---|---|---|
msgId | string | Server-assigned message ID of the card message that was triggered |
userId | string | ID of the user who triggered the button |
value | string | Button parameter saved when the card was sent; an omitted or null value becomes an empty string |
The body contains no button index, robotCode, App Secret, or other client fields. value is the string saved with the card and must not be treated as an arbitrary JSON object submitted by the client.
Signature algorithm
The callback body remains in its original JSON bytes; the platform does not AES-encrypt the body. The app backend uses HMAC-SHA256 to verify the source and body integrity, while HTTPS provides transport confidentiality.
signingInput = X-Link-Timestamp + "\n" + rawBody
signature = Base64(HMAC-SHA256(AppSecret, signingInput))
| Item | Fixed rule |
|---|---|
| Key | UTF-8 bytes of the sending app's current App Secret. Use the full text directly; do not Base64-decode or pre-hash it, and do not use access_token |
| Timestamp | Use the original decimal string from X-Link-Timestamp; do not convert it before concatenation |
| Concatenation | UTF-8 timestamp bytes + one newline byte 0x0A + original HTTP body bytes. Use neither the two literal characters \n nor CRLF |
| Output | Standard Base64 encoding of the 32-byte HMAC result, retaining = padding. Do not use hexadecimal or Base64URL |
| Comparison | Base64-decode X-Link-Signature, then compare it with a constant-time comparison |
Keep the original body bytes before parsing JSON. Changes to whitespace, escaping, field order, or newlines produce a different signature. Parse and validate msgId, userId, and value only after signature verification succeeds.
Node.js verification example
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);
}
Response constraints
After verifying the signature and processing the business action, return a JSON object with Content-Type: application/json. A callback succeeds only when the HTTP status is 2xx and the response body's code is the number 0.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
code | integer | Yes | Business result code: the number 0 indicates success; any other integer indicates failure. The string "0" is invalid |
msg | string / null | No | Result description. Leading and trailing whitespace is removed; an omitted, null, or whitespace-only value becomes an empty string. An empty message is preserved on success; failures select an error description using the rules below |
data | Any JSON value | No | Business data: an object, array, string, number, boolean, or null. An omitted value becomes null. When the response structure is valid, the JSON value is preserved for both success and failure |
Success example
Return HTTP 200 OK:
{
"code": 0,
"msg": "Processed successfully",
"data": {
"requestId": "REQ-1001",
"status": "approved"
}
}
When no result description or business data is needed, the minimal success body is {"code":0}.
Business failure example
Return HTTP 200 OK with a nonzero code to indicate a business failure:
{
"code": 1,
"msg": "This request has already been processed",
"data": {
"requestId": "REQ-1001",
"status": "already_processed"
}
}
Status and error handling
| Response | Result |
|---|---|
HTTP 2xx with a valid response object and code: 0 | Success; msg and data are preserved |
HTTP 2xx with a valid response object and a nonzero code | Business failure; data is preserved and an error description is selected |
HTTP outside 2xx | Failure, even when the body's code is 0. data is still preserved when the response structure is valid |
Empty body, a body that is not a JSON object, missing code, a string code, or a msg that is neither a string nor null | Failure. 204 No Content also fails because its body is empty |
| Response body larger than 64 KiB (65,536 bytes) | Failure. The body is not parsed, and truncated content is not used as an error description or business data |
| Network error or timeout | Failure |
The error description is selected as follows:
- For a body matching the response structure, use a nonempty
msgfirst. - For a body that does not match the response structure, use the nonempty raw body after trimming whitespace. Other fields such as
messageorerrorare not extracted individually. - If no body description is available and HTTP is outside
2xx, use the HTTP status text, such as502 Bad Gateway. Oversized responses also use only the HTTP status to select a description.
3xx redirects are not followed. The total budget for one callback is 3 seconds, including reading the response body. Complete signature verification and the required durable write or reliable enqueue, then return the complete JSON response within this window.