Notifications

After your application creates a HIT, Mechanical Turk manages the events that lead to the HIT's completion. In many cases, your application only needs to call the GetReviewableHITs operation 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 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 the GetHIT operation periodically, checking the values of the HITStatus and assignment summary fields. Depending on how up-to-date you need the information to be, doing this would require downloading the HIT's field data many times, and most attempts would only tell you that nothing has happened since the last call.

The Mechanical Turk Requester Service provides a better way to keep track of HIT activity. You can set up notifications for any HIT type, and any of several kinds of events that occur during the HIT life cycle. When Mechanical Turk detects an event for which you've set up a notification, Mechanical Turk will attempt to notify you--or your application--that the event took place.

Notifications are specified as part of a HIT type. You can create or modify notifications for a HIT type with the SetHITTypeNotification operation. The operation accepts a notification specification, as the Notification parameter.

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

You can update, disable or enable a HIT type's notification specification at any time with the SetHITTypeNotification operation.

The simplest way to be notified of an event is by e-mail. If you establish a notification for an event using e-mail as the transport, when the event occurs, Mechanical Turk will send a human-readable e-mail message to an address you include in the notification specification.

Mechanical Turk can also send notifications directly to your application using a web service call. To accept notifications, your application must be connected to the Internet, and must be able to accept HTTP requests. Mechanical Turk can send a notification as either a SOAP web service message, or a REST-like HTTP request. For more information about developing a HIT notification receptor, see The Notification Receptor API.

Mechanical Turk can notify you when:

For example, instead of calling the GetReviewableHITs operation repeatedly to poll for results of a particular HIT type, you can establish a notification that triggers whenever a HIT of that type becomes "reviewable". Your application can listen for a SOAP or REST request that indicates when a HIT of the type is ready for review.

A notification message is only sent once. If your application is not available when the notification is sent, the notification is not sent a second time.

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 will send a single notification message that describes multiple events.

You can test your application's ability to receive notifications using the SendTestEventNotification operation. When you call this operation, Mechanical Turk will send a test notification according to the notification specification you provide.

For a notification sent as a SOAP or REST message, the message includes a signature, similar to the Signature parameter your application uses when sending requests to the Mechanical Turk Requester Service. Mechanical Turk uses your AWS secret key to sign notification messages. Your application can verify that the notification came from Mechanical Turk by generating a signature value from the other notification message fields using your AWS secret key, then comparing the result to the signature found in the message.

For more information about developing a HIT notification receptor, see The Notification Receptor API.