Document Moderation Result Callback

Overview

The document moderation service can push the asynchronous moderation result to your callback URL after the task is completed or failed. You need to provide an HTTP endpoint that follows this specification.

You can enable callback in either of the following ways:

• Configure a callback URL in <Console - Service Configuration>.
• Pass callbackUrl when calling the Document Moderation Task Submission API. The request-level callbackUrl takes precedence over the callback URL configured in the console.

Callback Request

• Request URL:

The callback URL configured by you or passed in the submit request.

• Request method:

POST

• HTTP request Header:

Interface Authentication

Client can perform interface authentication through the key information assigned after configuring callback parameters. The specific method is as follows:

• Signature Algorithm

  1> Sort the received request body parameters in ascending order of the ASCII code table.

  2> Append the sorted parameters into a string. The format is: key1 + value1 + key2 + value2....

  3> Append the key generated after configuring callback parameters to the string generated in step 2>.

  4> Encode the string generated in step 3> with UTF-8, calculate the MD5 hash to generate the signature value, and put it into the request Header.

• Example code

/**
 * Generate signature
 * @param secretKey key generated in Console-Service Configuration
 * @param params interface request parameter name and parameter value map, excluding signature parameter name
 * @return
 */
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);

    try {
        return DigestUtils.md5Hex(signBuilder.toString().getBytes("UTF-8"));
    } catch (UnsupportedEncodingException e) {
        // error
    }
    return null;
}

After a callback secret key is configured in the console service configuration, the callback request body uses the following structure:

If no callback secret key is configured, the service directly pushes the result in the “Callback result JSON” structure below and does not send signature.

• Callback result JSON:

items:

tags:

subTags:

• Callback request example:

{
  "errorCode": 0,
  "code": 0,
  "taskId": "task_**************************",
  "appId": "82100001",
  "inputType": "DOCUMENT",
  "documentType": 1,
  "strategyId": "DEFAULT",
  "result": 2,
  "items": [
    {
      "itemId": "document_text_1",
      "mediaType": "TEXT",
      "originalText": "Example document text",
      "filteredText": "Example **** text",
      "result": 2,
      "tags": [
        {
          "tag": 150,
          "subTags": [
            {
              "subTag": 150001
            }
          ]
        }
      ]
    },
    {
      "itemId": "document_image_1",
      "mediaType": "IMAGE",
      "result": 0
    }
  ]
}

• Callback request example with signature enabled:

{
  "appId": "82100001",
  "taskId": "task_**************************",
  "result": "{\"errorCode\":0,\"code\":0,\"taskId\":\"task_**************************\",\"appId\":\"82100001\",\"inputType\":\"DOCUMENT\",\"documentType\":1,\"strategyId\":\"DEFAULT\",\"result\":2,\"items\":[]}"
}

Callback Response

After receiving the callback request, your endpoint must return a JSON response. A response with code: 0 is treated as successful.

• Response example:

{
  "code": 0,
  "message": "success"
}

If the response body is empty, the response code is not 0, the request times out, or the callback endpoint returns an error, the service will retry the callback. The retry interval starts at 1 second, and the service retries up to 3 times.