Skip to main content

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​

ItemRule
MethodPOST
Content-Typeapplication/json
X-Link-TimestampDecimal Unix timestamp string in milliseconds
X-Link-SignatureHMAC-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"}
FieldTypeDescription
msgIdstringServer-assigned message ID of the card message that was triggered
userIdstringID of the user who triggered the button
valuestringButton 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))
ItemFixed rule
KeyUTF-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
TimestampUse the original decimal string from X-Link-Timestamp; do not convert it before concatenation
ConcatenationUTF-8 timestamp bytes + one newline byte 0x0A + original HTTP body bytes. Use neither the two literal characters \n nor CRLF
OutputStandard Base64 encoding of the 32-byte HMAC result, retaining = padding. Do not use hexadecimal or Base64URL
ComparisonBase64-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​

FieldTypeRequiredDescription
codeintegerYesBusiness result code: the number 0 indicates success; any other integer indicates failure. The string "0" is invalid
msgstring / nullNoResult 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
dataAny JSON valueNoBusiness 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​

ResponseResult
HTTP 2xx with a valid response object and code: 0Success; msg and data are preserved
HTTP 2xx with a valid response object and a nonzero codeBusiness failure; data is preserved and an error description is selected
HTTP outside 2xxFailure, 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 nullFailure. 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 timeoutFailure

The error description is selected as follows:

  1. For a body matching the response structure, use a nonempty msg first.
  2. For a body that does not match the response structure, use the nonempty raw body after trimming whitespace. Other fields such as message or error are not extracted individually.
  3. If no body description is available and HTTP is outside 2xx, use the HTTP status text, such as 502 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.