# Managing Notifications
<a name="ApiReference_NotificationReceptorAPIArticle"></a>

**Topics**
+ [Elements of a Notification Message](ApiReference_NotificationAPI_ElementsOfANotification.md)
+ [Notification Handling Using Amazon SQS](ApiReference_NotificationReceptorAPI_SQSTransportArticle.md)
+ [Notification Handling Using Amazon SNS](ApiReference_NotificationReceptorAPI_SNSTransportArticle.md)
+ [Notification](ApiReference_NotificationDataStructureArticle.md)

This section describes how to set up and handle Amazon Mechanical Turk event notification messages. A notification message describes one or more events that happened in regards to a HIT type. For more information, see [Elements of a Notification Message](ApiReference_NotificationAPI_ElementsOfANotification.md). 

You can configure Amazon Mechanical Turk to notify you whenever certain events occur during the life cycle of a HIT. Mechanical Turk can send you a notification message 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. 

Notifications are specified as part of a HIT type. To set up notifications for a HIT type, you call the [UpdateNotificationSettings](ApiReference_UpdateNotificationSettingsOperation.md) operation with a HIT type ID and a notification specification. For more information about HIT types, see [Understanding HIT Types](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMechanicalTurkRequester/Concepts_HITTypesArticle.html). 

A notification specification is defined by a [Notification](ApiReference_NotificationDataStructureArticle.md) data structure, which describes a HIT event notification for the HIT type. The notification specification is passed as the `Notification` parameter when calling [UpdateNotificationSettings](ApiReference_UpdateNotificationSettingsOperation.md). 

Amazon Mechanical Turk can send a notification to an Amazon Simple Queue Service (Amazon SQS) queue or to an Amazon Simple Notification Service (Amazon SNS) topic. 

For more information about setting up and handling notifications, see [Creating and Managing Notifications](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMechanicalTurkRequester/Concepts_NotificationsArticle.html). 

 For more information on configuring notifications using SQS, see [Notification Handling Using Amazon SQS](ApiReference_NotificationReceptorAPI_SQSTransportArticle.md). 

 For more information on configuring notifications using SNS, see [Notification Handling Using Amazon SNS](ApiReference_NotificationReceptorAPI_SNSTransportArticle.md). 

You can test your application's ability to receive notifications using [SendTestEventNotification](ApiReference_SendTestEventNotificationOperation.md). 

# Elements of a Notification Message
<a name="ApiReference_NotificationAPI_ElementsOfANotification"></a>

Notification messages contain one or more `Event` data structures that describe recent activity for HITs of a HIT type.

## The Notification API Version
<a name="ApiReference_NotificationAPI_ElementsOfANotification-the-notification-api-version"></a>

Similar to how a REST request that is sent to the Amazon Mechanical Turk Requester service must include a `Version` parameter to indicate which version of the service API the client is expecting to use, a notification message must also include a `Version` parameter. This version string is identical to the version that is included in the notification specification for the HIT type. 

**Tip**  
 Your application may need to accommodate receiving notification messages of different versions at the same time if you want to upgrade your notification specifications to a new version without missing messages. You can avoid having to accommodate multiple API versions by first disabling the notification specifications that use the old version, upgrading your application to use the new version, then updating the notification specifications to use the new version and re-enable notifications. 

 When a new version of the notification API is made available, all existing notification specifications will continue to use the API versions they were using previously. You must update your notification specifications to use a new version of the API. 

## Events
<a name="ApiReference_NotificationAPI_ElementsOfANotification-events"></a>

 A notification message describes one or more events that happened in regards to a HIT type. Each event includes: 
+ the event type (`EventType`), a value corresponding to the `EventType` value in the [notification specification data structure](ApiReference_NotificationDataStructureArticle.md)
+ the time of the event (`EventTime`), as a [dateTime](http://www.w3.org/TR/xmlschema-2/#dateTime) in the Coordinated Universal Time time zone, such as **2005-01-31T23:59:59Z**
+ the HIT type ID for the event (`HITTypeId`)
+ the HIT ID for the event (`HITId`)
+ the assignment ID for the event, if applicable (`AssignmentId`)

 Multiple events may be batched into a single notification message. 

# Notification Handling Using Amazon SQS
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle"></a>

Your application can use the Amazon Simple Queue Service (Amazon SQS) to handle Mechanical Turk notifications. By using Amazon SQS, your notifications are guaranteed to be delivered at least once. For more information about guaranteed delivery of notifications, see [Guaranteed Delivery](#ApiReference_NotificationReceptorAPI_SQSTransportArticle-guaranteed-delivery). For more information about, see [Amazon SQS](http://aws.amazon.com/sqs/).

## Creating an SQS Queue
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-creating-queue"></a>

You must create an Amazon SQS queue before using the SQS transport type in notification-related calls. Mechanical Turk does not create an Amazon SQS queue for you. An SQS queue can be created through the Amazon SQS API or by using the [AWS Console](http://aws.amazon.com/console/). For more information, see the [Amazon SQS documentation](http://aws.amazon.com/documentation/sqs/).

## Configuring an SQS Queue
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-configuring-queue"></a>

Your Amazon SQS queue permissions must be configured to allow a Mechanical Turk system account to call the `sqs:SendMessage` action on your queue. Whether you use the management console UI or the API to configure permissions, consider the following:
+ You must add a permission that enables the Mechanical Turk service principal **mturk-requester.amazonaws.com** to call [SendMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySendMessage.html) on your queue.
+ Your [SendMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySendMessage.html) permission must add an action of `aws:SecureTransport` set to **true**.
+ Limit the permissions you apply to this queue to those that will actually be used.
+ You should consider disallowing all other access to your queue from other accounts.

  This makes it easy for you to be sure that available messages were sent by Mechanical Turk.

  If you enable [SendMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySendMessage.html) for other accounts to this queue, or if you plan to send messages to this queue from your AWS account, you should check the sending identity for every message that you receive from the queue. You can do this by requesting the `SenderId` attribute in your call to [ReceiveMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QueryReceiveMessage.html). This value will be **AIDAIXO4EZE6RHVSXIN4E**. Amazon SQS provides this value as a strong guarantee of the authenticated identity of the sender, so if it matches, you can be sure the message came from Mechanical Turk.

  For more information, see the [Amazon SQS Developer Guide](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/Welcome.html) and [Amazon SQS API Reference](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Welcome.html).

## Amazon SQS Policy Document Example
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-policy-document"></a>

 The following example policy document only creates the [SendMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySendMessage.html) permission for the Mechanical Turk account. You can add additional restrictions. For more information about policy documents, see the [Amazon SQS Developer Guide](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/Welcome.html).

## Configuring Permissions Using the AWS Console
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-config-console"></a>

**To configure permissions in the AWS Console:**

1. Sign in to the AWS Management Console and open the Amazon SQS console at [https://console.aws.amazon.com/sqs/](https://console.aws.amazon.com/sqs/).

1. Select your queue, and then select **Permissions**.

1. Click **Edit Policy Document**.

1. Enter a policy document similar to the example.

## Configuring Permissions Using the Amazon SQS API
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-config-api"></a>

 Call the Amazon SQS [SetQueueAttributes](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySetQueueAttributes.html) action with the `Attribute.Name` parameter set to **Policy**. You can call `SetQueueAttributes` with a policy document similar to the example policy document. Do not use the Amazon SQS `AddPermission` action for configuring permissions on this queue. If you programmatically create a queue and apply a policy document to it, you must ensure the `Resource` value in the policy document is updated with the correct queue name. 

## Testing Your Queue
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-testing-queue"></a>

To test your permissions, call the Mechanical Turk [SendTestEventNotification](ApiReference_SendTestEventNotificationOperation.md) operation with a `Transport` of **SQS** and your queue URL as the `Destination`.

## Guaranteed Delivery
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-guaranteed-delivery"></a>

Using Amazon SQS provides a guaranteed at-least-once delivery of each message. Mechanical Turk ensures that it calls [SendMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySendMessage.html) at least once for each message. SQS then provides guarantees regarding message persistence and message delivery.

Rarely, the same message may show up twice in the queue. This is an attribute of Amazon SQS's nature as a distributed system.

 If you take action on your queue that prevents Mechanical Turk from publishing to it, we cannot guarantee delivery of the messages that would have been sent to your queue. For instance, such actions may include: 
+ Modifying the permissions on your queue in a way that prevents our account from calling [SendMessage](http://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Query_QuerySendMessage.html) successfully.
+ Deleting or disabling your queue.

## SQS Message Ordering
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-message-ordering"></a>

You should expect that messages may arrive out of order. For information about message ordering behavior, see the [SQS documentation](http://aws.amazon.com/documentation/sqs/).

## Multiple SQS Queues
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-multiple-queues"></a>

You may use a different queue for each HITType that you configure with notifications.

Mechanical Turk does not provide the ability to route events within a HITType to different queues. For example, you might prefer to have AssignmentSubmitted events for a HITType delivered to a different queue than HITReviewable events for that same HITType. Mechanical Turk will publish both events to the same queue. You can split the events into different queues by running an SQS client that pulls the messages and republishes them to different queues depending on the event type.

## SQS Message Payload
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-message-payload"></a>

The body of each SQS message is a JSON-encoded structure that provides support for multiple events in each message.

The JSON-encoded structure contains the following: 
+ EventDocVersion: This is the requested version that is passed in the call to [UpdateNotificationSettings](ApiReference_UpdateNotificationSettingsOperation.md), such as **2014-08-15**. For a requested version, Mechanical Turk will not change the structure or definition of the output payload structure in a way that is not backward-compatible.
+ EventDocId: A unique identifier for the Mechanical Turk event. In rare cases, you may receive two different SQS messages for the same event, which can be detected by tracking the EventDocId values you have already seen.
+ CustomerId: Your Customer Id.
+ Events: A list of Event structures, described next.

The Event structure contains the following: 
+ EventType: A value corresponding to the EventType value in the notification specification data structure.
+ EventTimestamp: A dateTime in the Coordinated Universal Time time zone, such as **2005-01-31T23:59:59Z**.
+ HITTypeId: The HIT type ID for the event.
+ HITId: The HIT ID for the event.
+ AssignmentId: The assignment ID for the event, if applicable.

## Double Delivery
<a name="ApiReference_NotificationReceptorAPI_SQSTransportArticle-double-delivery"></a>

Amazon SQS already provides a `MessageId` value that enables double-delivery detection in the typical SQS case. However, when receiving messages from Mechanical Turk, we recommend that you use the EventDocId value for double-delivery detection. This will cover an additional scenario in which you may see the same EventDocId in two messages with distinct MessageIds.

Most messages are safe to process twice, since they represent independent one-way state changes. Consider whether detection of repeated messages is important for your application. You may be able to simply process the message and ignore it if it appears to have been applied already.

# Notification Handling Using Amazon SNS
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle"></a>

 Your application can use the Amazon Simple Notification Service (Amazon SNS) to handle Mechanical Turk notifications. For more information about Amazon SNS, see [Amazon SNS](http://aws.amazon.com/sns/).

## Creating an SNS Topic
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-creating-topic"></a>

 You must create an Amazon SNS topic before using the SNS transport type in notification-related calls. Mechanical Turk does not create an Amazon SNS topic for you. An SNS topic can be created through the Amazon SNS API or by using the [AWS Console](http://aws.amazon.com/console/). For more information, see the [Amazon SNS documentation](http://aws.amazon.com/documentation/sns/).

## Configuring an SNS Topic
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-configuring-topic"></a>

Your Amazon SNS topic permissions must be configured to allow a Mechanical Turk system account to publish to your topic. Whether you use the management console UI or the API to configure permissions, consider the following:
+ You must add a permission that enables the Mechanical Turk service principal **mturk-requester.amazonaws.com** to [Publish](http://docs.aws.amazon.com/sns/latest/api/API_Publish.html) to your topic.
+  You should ensure that only notifications from your Mechanical Turk account can be published to your topic. This can be done using a `StringEquals` IAM Policy Condition for the IAM Policy Condition Key `aws:SourceAccount` in your SNS Topic Policy doc. Set the `aws:SourceAccount` value equal to the AWS Account Id that is linked to your Mechanical Turk account. 

   You can determine the AWS Account Id that is linked to your Mechanical Turk account by visiting the [Mechanical Turk Developer](https://requester.mturk.com/developer) page. 

   For more information on the use of IAM Policy Conditions, see the [ IAM Policy Condition Element documentation](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements.html#Condition). 
+ Your [Publish](http://docs.aws.amazon.com/sns/latest/api/API_Publish.html) permission must add an action of `aws:SecureTransport` set to **true**.
+ Limit the permissions you apply to this topic to those that will actually be used.
+ You should consider disallowing all other access to your topic from other accounts.

  This makes it easy for you to be sure that all messages were sent by Mechanical Turk.

  For more information, see the [Amazon SNS Developer Guide](http://docs.aws.amazon.com/sns/latest/dg/welcome.html) and [Amazon SNS API Reference](http://docs.aws.amazon.com/sns/latest/api/Welcome.html).

## Amazon SNS Policy Document Example
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-policy-document"></a>

 The following example policy document only creates the [Publish](http://docs.aws.amazon.com/sns/latest/api/API_Publish.html) permission for the Mechanical Turk account. You can add additional restrictions. For more information about policy documents, see the [Amazon SNS Developer Guide](http://docs.aws.amazon.com/sns/latest/dg/welcome.html).

## Configuring Permissions Using the AWS Console
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-config-console"></a>

**To configure permissions in the AWS Console:**

1. Sign in to the AWS Management Console and open the Amazon SNS console at [https://console.aws.amazon.com/sns/](https://console.aws.amazon.com/sns/).

1. Select your topic, and then select **Actions**.

1. Click **Edit Topic Policy**.

1. Enter a policy document similar to the example.

## Configuring Permissions Using the Amazon SNS API
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-config-api"></a>

 Call the Amazon SNS [SetTopicAttributes](http://docs.aws.amazon.com/sns/latest/api/API_SetTopicAttributes.html) action with the `AttributeName` parameter set to **Policy**. You can call `SetTopicAttributes` with a policy document similar to the example policy document. Do not use the Amazon SNS `AddPermission` action for configuring permissions on this topic. If you programmatically create a topic and apply a policy document to it, you must ensure the `Resource` value in the policy document is updated with the correct topic name. 

## Testing Your Topic
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-testing-topic"></a>

To test your permissions, call the Mechanical Turk [SendTestEventNotification](ApiReference_SendTestEventNotificationOperation.md) operation with a `Transport` of **SNS** and your topic ARN as the `Destination`.

## SNS Message Payload
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-message-payload"></a>

The body of each SNS message is a JSON-encoded structure that provides support for multiple events in each message.

The JSON-encoded structure contains the following: 
+ EventDocVersion: This is the requested version that is passed in the call to [UpdateNotificationSettings](ApiReference_UpdateNotificationSettingsOperation.md), such as **2014-08-15**. For a requested version, Mechanical Turk will not change the structure or definition of the output payload structure in a way that is not backward-compatible.
+ EventDocId: A unique identifier for the Mechanical Turk event. In rare cases, you may receive two different SNS messages for the same event, which can be detected by tracking the EventDocId values you have already seen.
+ CustomerId: Your Customer Id.
+ Events: A list of Event structures, described next.

The Event structure contains the following: 
+ EventType: A value corresponding to the EventType value in the notification specification data structure.
+ EventTimestamp: A dateTime in the Coordinated Universal Time time zone, such as **2005-01-31T23:59:59Z**.
+ HITTypeId: The HIT type ID for the event.
+ HITId: The HIT ID for the event.
+ AssignmentId: The assignment ID for the event, if applicable.

## Double Delivery
<a name="ApiReference_NotificationReceptorAPI_SNSTransportArticle-double-delivery"></a>

When receiving messages from Mechanical Turk, we recommend that you use the `EventDocId` value for double-delivery detection.

Most messages are safe to process twice, since they represent independent one-way state changes. Consider whether detection of repeated messages is important for your application. You may be able to simply process the message and ignore it if it appears to have been applied already.

# Notification
<a name="ApiReference_NotificationDataStructureArticle"></a>

## Description
<a name="ApiReference_NotificationDataStructureArticle-description"></a>

 The Notification data structure describes a HIT event notification for a HIT type. 

## Elements
<a name="ApiReference_NotificationDataStructureArticle-elements"></a>

 The Notification structure can contain the elements described in the following table. When the structure is used in a request, elements described as **Required** must be included for the request to succeed. 


| Name | Description | Required | 
| --- | --- | --- | 
|   `Destination`   |  The destination for notification messages.  Type: String [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_NotificationDataStructureArticle.html) Default: None  |  Yes  | 
|   `Transport`   |  The method Amazon Mechanical Turk uses to send the notification. Type: String Valid Values: SQS \$1 SNS Default: None  |  Yes  | 
|   `Version`   |  The version of the Notification data structure schema to use. Type: String Valid Values: 2014-08-15 Default: None  |  Yes  | 
|   `EventTypes`   |  The array of one or more events that should cause notifications to be sent. The Ping event is only valid for the [SendTestEventNotification](ApiReference_SendTestEventNotificationOperation.md) operation. Type: Array of Strings Valid Values: AssignmentAccepted \$1 AssignmentAbandoned \$1 AssignmentReturned \$1 AssignmentSubmitted \$1 AssignmentRejected \$1 AssignmentApproved \$1 HITCreated \$1 HITExtended \$1 HITDisposed \$1 HITReviewable \$1 HITExpired \$1 Ping Default: None  |  Yes  | 

## Example
<a name="ApiReference_NotificationDataStructureArticle-example"></a>

In the following example, the notification specification specifies that an event notification message will be published to an SNS topic when a Worker accepts a HIT. 

```
{
  Destination:"arn:aws:sns:us-east-1:7429088EXAMPLE:my_mturk_topic",
  Transport: "SNS",
  Version:"2014-08-15",
  EventTypes:["AssignmentAccepted"]
}
```