Asynchronous Text Check Result Callback

Update:

Receive asynchronous text moderation results, identified by taskId.

POSTcallbackUrl

Callback Configuration

  1. Configure the HTTP callback URL, callback region, and generated secret key in Console → Service Configuration.
  2. Alternatively, pass callbackUrl and callbackSecretKey when submitting a task.

Task parameters take priority over the console settings. Both callback URL and secret key must be non-empty when supplied through the task API.

Request Parameters

Request Headers

Both headers are required.

Header Value Description
Content-Type application/json JSON request body
signature — Verify using Callback Signature below

Request Body

Field Type Description
appId String Project ID
taskId String Task ID returned by submission
result JSON String Moderation result serialized as a JSON string

Parse the result string to obtain the result object. Its code field is reserved and should be ignored.

result

Field Type Description
code Number Reserved; ignore this field
textSpam TextSpam Text moderation result
warning Boolean Custom advertising-word alert configured in the console blacklist
taskId String Unique identifier of the detection task
language String Detected language
startTime Number Timestamp when detection was called
endTime Number Timestamp when the result was returned

textSpam

After parsing result: textSpam.

Field Type Description
content String Text with sensitive words replaced by asterisks; other content is unchanged
result Number 0: pass; 1: review recommended; 2: fail
tags List<Tag> First-level classifications
wordList String[] Sensitive words

tags[]

After parsing result: textSpam.tags.

Field Type Description
tag Number First-level category code; see Classification Codes.
tagName String First-level category name
tagNameEn String First-level category name in English
level Number 0: normal; 1: suspected; 2: abnormal
confidence Number Advertising confidence, 0–100; returned only when tag is 150
subTags List<SubTag> Second-level classifications

subTags[]

After parsing result: textSpam.tags[].subTags.

Field Type Description
subTag Number Second-level code; see Classification Codes
subTagName String Second-level category name
subTagNameEn String Second-level category name in English
wordList String[] Matched words

Request Example

{
  "appId": "1000",
  "taskId": "c01b212f-3e31-4a2e-8346-b6f6ce3a3456",
  "result": "{\"code\":0,\"textSpam\":{\"content\":\"****\",\"result\":2,\"tags\":[{\"tag\":160,\"level\":2,\"tagName\":\"辱骂\",\"tagNameEn\":\"insults\",\"subTags\":[{\"subTag\":160001,\"subTagName\":\"谩骂人身攻击\",\"subTagNameEn\":\"insults and personal attacks\",\"wordList\":[\"fuck\"]}]}],\"wordList\":[\"fuck\"]},\"taskId\":\"c01b212f-3e31-4a2e-8346-b6f6ce3a3456\",\"language\":\"English\",\"startTime\":1660103900367,\"endTime\":1660103900374}"
}

Callback Signature

Use the callback secret key to verify the signature header.

  1. Sort request parameter names in ascending ASCII order.
  2. Concatenate each name and value as key1 + value1 + key2 + value2 + ....
  3. Append the callback secret key.
  4. Encode the string as UTF-8 and compute its MD5 hexadecimal digest. Compare it with signature.

Signature Example

public static String signature(String secretKey, Map<String, String> params) {
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);
    StringBuilder signBuilder = new StringBuilder();
    for (String key : keys) {
        signBuilder.append(key).append(params.get(key));
    }
    signBuilder.append(secretKey);
    return DigestUtils.md5Hex(signBuilder.toString().getBytes(StandardCharsets.UTF_8));
}

The example uses java.util.Arrays, java.util.Map, java.nio.charset.StandardCharsets, and Apache Commons Codec DigestUtils.

Callback Response

Return a JSON acknowledgement. The response body code is 0 on success; the documented failure values are 500 or 4xx.

Parameter Type Required Description
code Number Required 0 indicates successful callback processing
message String Optional Additional details 
{
  "code": 0
}

Failure Handling

Keep the receiving endpoint available. Failed deliveries are sent three times at 10-second intervals; delivery stops if the third attempt fails. Retrieve the result through Check Result Query if needed.