All Products
Search
Document Center

Content Moderation:Enable callback notifications

Last Updated:Jul 19, 2023

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 business purposes, you can enable callback notifications. This topic describes how to enable callback notifications for the Content Moderation API.

Background information

The Content Moderation API supports callback notifications for machine-assisted moderation results and human review results.

  • Callback notification for machine-assisted moderation results: After a moderation request is processed, Content Moderation sends the machine-assisted moderation results to the specified HTTP callback URL by sending an HTTP POST request.

  • 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 sending an HTTP POST request. For more information, see Review machine-assisted moderation results.

Terms

The following table introduces the concepts related to callback notifications.

Term

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:

  • Use HTTP or HTTPS and be accessible from the Internet.

  • Support the POST method.

  • Support UTF-8-encoded data.

  • Support data that is received in the application/x-www-form-urlencoded format.

  • Support the checksum and content parameters in callback data.

Seed

The string that is used to verify whether the POST 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 Content Moderation receives an HTTP status code other than 200, Content Moderation continues to push the callback notification until your server receives it. Content Moderation can repeatedly push a callback notification for up to 3 times.

callback data

The content of the callback notification that Content Moderation sends to the specified callback URL. For more information about the parameters in the callback data, see Parameters in the callback data.

Table 1. Parameters in the callback data

Name

Type

Description

checksum

String

The string in the <UID> + <Seed> + <Content> format that is generated by using the Secure Hash Algorithm 256 (SHA-256) algorithm. UID indicates the ID of your Alibaba Cloud account. To view the account ID, you can log on to the Alibaba Cloud console and move the pointer over the profile picture in the upper-right corner.

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 value.

content

String

The JSON-formatted string to be parsed to the callback data in the JSON format. For more information about the callback data that is 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 notifications, including asynchronous image moderation and asynchronous video moderation. For more information, see asynchronous image moderation and asynchronous video moderation. If you call an asynchronous operation and need Content Moderation to return the moderation results, set the callback and seed parameters in your moderation request. The callback parameter specifies the callback URL and the seed parameter specifies a string that is used to verify the callback notification request.

Note

If you do not set the preceding parameters when you call an asynchronous operation, you can only poll the asynchronous moderation results at regular intervals.

Procedure

  1. Prepare the HTTP callback URL and seed parameters that are used to receive moderation results.

  2. When you call an asynchronous operation for content moderation, set the callback and seed parameters in your moderation request. For more information, see the parameter description of the relevant API operation.

Callback notification for human review results

If you send human review requests, the review results are not returned in real time. You must configure callback notifications to receive human review results.

  • Use both the machine-assisted moderation and human review services

    If you use both the machine-assisted moderation and human review services, you must configure a callback notification for human review results in the Content Moderation console. To configure a callback notification in the console, perform the following steps:

    1. Log on to the Content Moderation console.

    2. In the left-side navigation pane, choose Machine audit > Settings.

    3. On the Machine audit page, click the Notification tab. Then click Create New Notification on this tab.

    4. In the Create New Notification dialog box, set the Title, Callback URL, Encryption algorithm, Notification type, and Audit Result parameters. Then, click OK.

      After you configure the callback notification, 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. Save the generated value of the seed parameter.

      Important
      • If you have configured a callback notification for machine-assisted moderation results, you can reuse the configurations of the callback notification or configure another callback notification based on your business requirements.

      • You can configure a callback notification for receiving all moderation results or only specified moderation results based on your business scenario.

      • Select Manual Review Results by AlibabaCloud for the Notification type parameter.

      • Valid values of the Encryption algorithm parameter:

        • SHA256: The HMAC-SHA256 encryption algorithm is used.

        • SM3: The HMAC-SM3 encryption algorithm is used and a hexadecimal string is returned. The string consists of lowercase letters and digits.

          For example, 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 is returned after you encrypt abc by using the HMAC-SM3 encryption algorithm.

    5. On the BizType Manage tab, find the business scenario that you want to manage, click Choose Notification Plan in the Actions column, and then select a callback notification scheme from the Callback notification scheme drop-down list for the business scenario.

Content parameter description

After you enable callback notifications, Content Moderation sends the moderation results that are 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

Element

Type

Required

Description

scanResult

JSONObject

No

The machine-assisted moderation result. The structure of this parameter varies based on the moderated objects, such as images and videos.

  • For images, the structure is the same as that of the results parameter that is returned in response to synchronous operations for image moderation. For more information, see synchronous image moderation.

  • For videos, the structure is the same as that of the results parameter that is returned in response to asynchronous operations for video moderation. For more information, see asynchronous video moderation.

auditResult

JSONObject

No

The human review result that is 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

JSONObject

No

The human review result that is generated by the human review service of Alibaba Cloud. This parameter is returned only if you purchase the human review service of Alibaba Cloud. For more information, see humanAuditResult.

Table 3. auditResult

Element

Type

Required

Description

suggestion

String

Yes

The suggestion that you provided during human review. Valid values:

  • block

  • pass

labels

JSONArray

No

The tag that you set during human review. The return value can be one or more tags. Valid values:

  • porn: pornographic content

  • terrorism: terrorist content

  • ad : text or image ads

  • live: undesirable scenes

Table 4. humanAuditResult

Element

Type

Required

Description

suggestion

String

Yes

The suggestion that is 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

JSONArray

No

The tag that the human review service sets. The return value can contain multiple tags.

Note

By default, this parameter is not returned. If you want this parameter to be returned, contact Alibaba Cloud technical support and pay a fee.

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": [
              "porn",
              "vulgar"
        ],
        "taskId": "xxxxxx"
    }
}