Content Moderation can send asynchronous notifications to inform you of machine-assisted moderation results and your review results. If you want to use or integrate the results for your business purpose, you can enable callback notification. This topic describes how to enable callback notification for the Content Moderation API.

Background information

Content Moderation supports callback notification for machine-assisted moderation results and human review results.
  • Callback notification for machine-assisted moderation results: After processing a moderation request, Content Moderation sends the machine-assisted moderation results to the specified HTTP callback URL by using the POST method.
  • Callback notification for human review results: After you review data or call feedback operations to rectify the machine-assisted moderation results, Content Moderation sends the human review results to the specified HTTP callback URL by using the POST method. For more information, see Review data.

Concepts

The following table introduces the concepts related to callback notification.

Concept Description
Callback URL The public endpoint of your server that you specify in the Alibaba Cloud Content Moderation console. The callback URL must meet the following requirements:
  • An HTTP or HTTPS URL that can be accessed over the Internet.
  • Supports the POST method.
  • Supports data encoded in UTF-8 format.
  • Supports receiving data in the application/x-www-form-urlencoded format.
  • Supports the checksum and content parameters in callback data.
Seed The string used to verify whether the request is sent from Content Moderation to the specified HTTP callback URL.
Callback times The number of times that Content Moderation pushes callback notifications to your server. If your server receives a callback notification, it sends the HTTP status code 200 to Content Moderation. If your server fails to receive a callback notification, it sends other HTTP status codes to Content Moderation. After receiving an HTTP status code other than 200, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can push a callback notification repeatedly for up to 16 times.
Callback data The content of the callback notification that Content Moderation sends to the specified callback URL. The following table describes the parameters in the callback data.
Table 1. Parameters in the callback data
Parameter Type Description
checksum String The string in the <UID> + <Seed> + <Content> format generated by the Secure Hash Algorithm 256 (SHA-256) algorithm. UID indicates the ID of your Alibaba Cloud account. You can query the ID in the Alibaba Cloud console.
Note To prevent data tampering, you can use the SHA-256 algorithm to generate a string when your server receives a callback notification and verify the string against the received checksum parameter.
content String The JSON-formatted string to be parsed to the callback data in JSON format. For more information about the callback data parsed from the content parameter, see the Content parameter description section of this topic.

Callback notification for machine-assisted moderation results

All asynchronous moderation operations of the Content Moderation API support callback notification, including asynchronous image moderation and asynchronous video moderation. If you call an asynchronous operation and need Content Moderation to return the moderation results, specify the callback and seed parameters in your moderation request. The callback parameter specifies the callback URL and the seed parameter specifies a string used to verify the callback notification request.

Note If you do not specify the preceding parameters when you call an asynchronous operation, you can only poll the asynchronous moderation results at regular intervals.
  1. Prepare the HTTP callback URL and verification string for receiving moderation results.
  2. When you call an asynchronous operation for content moderation, specify the callback and seed parameters in your moderation request. For more information, see the parameter description of relevant API operation.

Callback notification for human review results

  1. Log on to the Alibaba Cloud Content Moderation console.
  2. In the left-side navigation pane, choose Settings > Moderation API.
  3. On the Moderation API page that appears, click the Message tab.
  4. In the Settings for Audit Result Notification section, click Settings or View.
    Note If you have not specified a callback URL, Settings appears. If you have specified a callback URL, View appears.
    Go to the Message tab
  5. In the Callback Settings pane that appears on the right, set Callback URL and click Settings.
    After the callback URL is specified, the system automatically generates a value for the seed parameter. You can use the value of the seed parameter to verify whether a callback notification request is sent from Alibaba Cloud to the callback URL. Save and use the value of the seed parameter based on your business needs.Specify a callback URL

Content parameter description

After callback notification is enabled, Content Moderation sends the moderation results generated by the Content Moderation API in a callback notification to the specified callback URL. The callback notification contains the content parameter. The following tables describe the structure of the content parameter.

Table 2. Structure of the content parameter
Parameter Type Required Description
scanResult JSON object No The machine-assisted moderation result. The structure of this parameter varies depending on the moderation object, such as images and videos.
auditResult JSON object No The human review result generated by you. This parameter is returned only when human review is performed. For more information, see auditResult.
Note This parameter is not returned if Content Moderation sends only machine-assisted moderation results.
humanAuditResult JSON object No The human review result generated by the human review service of Alibaba Cloud. If you purchased the human review service of Alibaba Cloud, this parameter is returned to send the human review result. For more information, see humanAuditResult.
Table 3. auditResult
Parameter Type Required Description
suggestion String Yes The suggestion that you provided during human review. Valid values:
  • block
  • pass
labels JSON array Yes The tag that you set during human review. The returned value can be one or more tags. Valid values:
  • porn
  • terrorism
  • ad
  • live
Table 4. humanAuditResult
Parameter Type Required Description
suggestion String Yes The suggestion provided by the human review service of Alibaba Cloud. Valid values:
  • block
  • pass
taskId String Yes The ID of the moderation task. You can associate the human review result of the content with the corresponding machine-assisted moderation result based on the task ID.
dataId String Yes The ID of the moderated content.
labels String array No The tag that the human review service sets. The returned value can contain multiple tags.
Note This parameter is not returned by default. If this parameter is required, contact your business manager.
Example of the content parameter 
{
    "scanResult": {
        "code": 200,
        "msg": "OK",
        "taskId": "fdd25f95-4892-4d6b-aca9-7939bc6e9baa-1486198766695",
        "url": "http://1.jpg",
        "results": [
            {
                "rate": 100,
                "scene": "porn",
                "suggestion": "block",
                "label": "porn"
            }
        ]
    },
    "auditResult": {
        "suggestion": "block",
        "labels": [
            "porn",
            "ad",
            "terrorism"
        ]
    },
    "humanAuditResult": {
          "suggestion": "pass",
          "dataId": "yyyy",
          "labels": [
              "Pornographic content",
              "Vulgar content"
        ],
          "taskId": "xxxxxx"
    }
}