Building A Notification Receptor

You can tell Amazon Mechanical Turk to notify you whenever certain events occur that regard your HITs. Amazon Mechanical Turk can notify you when a Worker accepts, abandons, returns, or submits an assignment, when a HIT becomes "reviewable", or when a HIT expires, for any HIT of a given HIT type. To set up notifications for a HIT type, you call the SetHITTypeNotification operation with a HIT type ID and a notification specification.

Amazon Mechanical Turk can send a notification using one of several "transports". The simplest transport is a human-readable e-mail message sent to an e-mail address that you specify in the notification specification.

The other notification transports let Amazon Mechanical Turk contact your Requester application directly: The REST transport sends an HTTP request to a URL you specify containing the notification data as key-value pairs. The SOAP transport sends a SOAP web services request, an HTTP request with XML data in SOAP-standard envelope, to an "end-point" (URL) that you specify.

To use the REST or SOAP transports, you will need to build an application that can accept HTTP connections, and collect and process notification messages. This notification receptor application will need to be operational any time a notification message might be sent in order to receive the message.

	Note
	Notification messages are only sent once. Notifications are not sent again, even if the HTTP request returns with an error code or fails for any reason. Your application will need to tolerate missing some notification messages.

	Note
	Only ports 80 and 443 are supported for receiving notification messages.

This section describes the notification receptor API that your receptor will need to implement to receive and understand notification messages. For code samples that illustrate how to build a notification receptor, see the Amazon Web Services Resource Center.

For more information about notifications, see Notifications. For more information about creating, modifying or disabling notification specifications on HIT types, see the SetHITTypeNotification operation.

See also the SendTestEventNotification operation, and Notification.

What a Notification Receptor Should Expect

Your notification receptor will receive a notification message when a HIT event occurs that matches an active notification specification for the HIT type of the HIT, and the specification includes the receptor as the message destination.

A notification message may describe one or more events. If multiple events happen in a short period of time, they may be batched into a single message. Your receptor should expect messages to describe multiple events.

Your receptor should also expect to receive a "Ping" event at any time. "Ping" events are used for diagnostic purposes, and do not correspond to any HIT activity. Amazon Mechanical Turk will send a "Ping" notification when you call the SendTestEventNotification operation, and may also send "Ping" events to check the availability of your receptor at other times.