Creating and Managing Notifications

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 GetReviewableHITs 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 GetHIT 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 Amazon 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 Amazon Mechanical Turk detects an event for which you've set up a notification, Amazon Mechanical Turk will attempt to notify you--or your application--that the event took place.

	Important
	Every time you change your secret access key ID you need to reset each of your HITType notifications. When you do, Amazon Mechanical Turk uses your new secret access key ID to sign the notifications. Until you reset your notifications, Amazon Mechanical Turk will use your old secret access key ID to sign notifications. For more information, see SetHITTypeNotification.

Notifications are specified as part of a HIT type. You can create or modify notifications for a HIT type with SetHITTypeNotification. 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 RegisterHITType You can determine the HIT type of an existing HIT by calling GetHIT with the HIT's ID.

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

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, Amazon Mechanical Turk will send a human-readable e-mail message to an address you include in the notification specification.

Amazon 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. Amazon 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 Notification Receptor API.

Amazon Mechanical Turk can notify you when:

For example, instead of calling GetReviewableHITs 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, Amazon Mechanical Turk will send a single notification message that describes multiple events.

You can test your application's ability to receive notifications using SendTestEventNotification. When you call this operation, Amazon 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 Amazon Mechanical Turk Requester Service. Amazon Mechanical Turk uses your AWS secret key to sign notification messages. Your application can verify that the notification came from Amazon 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 Notification Receptor API.