Amazon Mechanical Turk
Developer Guide (API Version 2017-01-17)

Creating and Managing Notifications

Tracking HITs

After your application creates a HIT, Amazon Mechanical Turk manages the events that lead to the HIT's completion. In many cases, your application only needs to call ListReviewableHITs periodically until the HIT is returned as a result. The HIT becomes "reviewable" either when all of the HIT's assignments have been completed by Workers, or when the HIT's lifetime has elapsed (the HIT has expired).

Sometimes, it is useful to know more about the events that lead to the HIT becoming reviewable. One way to watch a HIT and its assignments change state is to call GetHIT periodically, checking the values of the HITStatus and assignment summary fields. Depending on how up-to-date you need the information to be, if you call GetHIT, you would have to download the HIT's field data many times, and most attempts would only tell you that nothing has happened since the last call.

The Amazon Mechanical Turk Requester service provides notifications as a more efficient way to keep track of HIT activity. You can set up notifications for any HIT type, specifying which type of HIT life cycle events you want to track. When Amazon Mechanical Turk detects an event that you've set up for notification, a message is sent to an Amazon Simple Queue Service (Amazon SQS) queue or an Amazon Simple Notification Service (Amazon SNS) topic.

For example, instead of calling ListReviewableHITs repeatedly to poll for results of a particular HIT type, you can call UpdateNotificationSettings to set that a notification be sent whenever a HIT of that type becomes "reviewable."

Setting Event Notifications

Notifications are specified as part of a HIT type. To set up notifications for a HIT type, you call the UpdateNotificationSettings operation with a HIT type ID and a notification specification. For more information about HIT types, see Understanding HIT Types.

A notification specification is defined by a Notification data structure, which describes a HIT event notification for the HIT type. The notification specification is passed as the Notification parameter when calling UpdateNotificationSettings.

The HIT type must already exist before you can give it a notification specification. You can create a new HIT type by calling CreateHITType. You can determine the HIT type of an existing HIT by calling GetHIT with the HIT's ID.

Notification Specification

A notification specification is defined by using a Notification data structure that is passed as the Notification parameter when calling SetHITTypeNotification. You can update, disable or enable a HIT type's notification specification at any time by calling UpdateNotificationSettings.

A notification specification can specify that a notification is sent when the following events occur.

  • A Worker accepts a HIT

  • A Worker abandons an assignment

  • A Worker returns an assignment

  • A Worker submits an assignment

  • A HIT becomes "reviewable"

  • A HIT expires

A notification specification also specifies the way the notifications are transported. Mechanical Turk can send event notifications by using the following two kinds of transport.

  • By using the Amazon Simple Queue Service (Amazon SQS)—Amazon Mechanical Turk can send notifications to Amazon SQS, which offers reliable and scalable hosted queues for storing messages.

    • An event notification message will always be delivered to SQS.

    • Notification messages can only be seen by customers who have access to your SQS queue.

    For more information, see Notification Handling Using Amazon SQS.

  • By using the Amazon Simple Notification Service (Amazon SNS)—Amazon Mechanical Turk can send notifications to Amazon SNS, which offers reliable and scalable push notifications to multiple destinations. Amazon Mechanical Turk guarantees event notifications will be delivered at least once to your SNS topic.

    For more information, see Notification Handling Using Amazon SNS.

Notification Messages

A notification message is sent when a HIT event that matches an active notification specification for the HIT type of the HIT occurs. A notification message for an event is sent within several minutes of the event occurring. If many events occur in a short period of time, Mechanical Turk may send a single notification message that describes multiple events.

For more information about notification messages, see Elements of a Notification Message.

Testing Notifications

You can test your application's ability to receive notifications by calling SendTestEventNotification.

For more information about notifications, see Notifications API.