Tutorial: Configuring an Amazon SNS dead-letter queue for a subscription - Amazon Simple Notification Service

Tutorial: Configuring an Amazon SNS dead-letter queue for a subscription

A dead-letter queue is an Amazon SQS queue that an Amazon SNS subscription can target for messages that can't be delivered to subscribers successfully. Messages that can't be delivered due to client errors or server errors are held in the dead-letter queue for further analysis or reprocessing. For more information, see Amazon SNS dead-letter queues and Message delivery retries.

The following tutorial shows how you can use the AWS Management Console, the AWS SDK for Java, the AWS CLI, and AWS CloudFormation to configure a dead-letter queue for an Amazon SNS subscription.

Prerequisites

Before you begin any of the following tutorials, complete the following prerequisites:

  1. Create an Amazon SNS topic named MyTopic.

  2. Create an Amazon SQS queue named MyEndpoint, to be used as the endpoint for the Amazon SNS subscription.

  3. (Skip for AWS CloudFormation) Subscribe the queue to the topic.

  4. Create another Amazon SQS queue named MyDeadLetterQueue, to be used as the dead-letter queue for the Amazon SNS subscription.

  5. To give Amazon SNS principal access to the Amazon SQS API action, set the following queue policy for MyDeadLetterQueue.

    { "Statement": [{ "Effect": "Allow", "Principal": { "Service": "sns.amazonaws.com" }, "Action": "SQS:SendMessage", "Resource": "arn:aws:sqs:us-east-2:123456789012:MyDeadLetterQueue", "Condition": { "ArnEquals": { "aws:SourceArn": "arn:aws:sns:us-east-2:123456789012:MyTopic" } } }] }

To configure a dead-letter queue for an Amazon SNS subscription using the AWS Management Console

Before your begin this tutorial, make sure you complete the prerequisites.

  1. Sign in to the Amazon SQS console.

  2. Create an Amazon SQS queue or use an existing queue and note the ARN of the queue on the Details tab of the queue, for example:

    arn:aws:sqs:us-east-2:123456789012:MyDeadLetterQueue
    Note

    Currently, you can't use an Amazon SQS FIFO queue as a dead-letter queue for an Amazon SNS subscription.

  3. Sign in to the Amazon SNS console.

  4. On the navigation panel, choose Subscriptions.

  5. On the Subscriptions page, select an existing subscription and then choose Edit.

  6. On the Edit 1234a567-bc89-012d-3e45-6fg7h890123i page, expand the Redrive policy (dead-letter queue) section, and then do the following:

    1. Choose Enabled.

    2. Specify the ARN of an Amazon SQS queue.

  7. Choose Save changes.

    Your subscription is configured to use a dead-letter queue.

To configure a dead-letter queue for an Amazon SNS subscription using the AWS SDK for Java

Before your begin this tutorial, make sure you complete the prerequisites.

  1. Specify your AWS credentials. For more information, see Set up AWS Credentials and Region for Development in the AWS SDK for Java 2.x Developer Guide.

  2. Write your code. For more information, see Using the SDK for Java 2.x.

    For more information about creating Amazon SQS queues, see To Configure an Amazon SQS Queue Using the AWS SDK for Java in the Amazon Simple Queue Service Developer Guide.

    The following code excerpt uses the ARN of an Amazon SNS subscription and an Amazon SQS queue to set the RedrivePolicy request parameter attribute.

    // Specify the ARN of the Amazon SNS subscription. String subscriptionArn = "arn:aws:sns:us-east-2:123456789012:MyEndpoint:1234a567-bc89-012d-3e45-6fg7h890123i"; // Specify the ARN of the Amazon SQS queue to use as a dead-letter queue. String redrivePolicy = "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-2:123456789012:MyDeadLetterQueue\"}"; // Set the specified Amazon SQS queue as a dead-letter queue // of the specified Amazon SNS subscription. SetSubscriptionAttributesRequest request = new SetSubscriptionAttributesRequest() .withSubscriptionArn(subscriptionArn) .withAttributeName("RedrivePolicy") .withAttributeValue(redrivePolicy); sns.setSubscriptionAttributes(request);
  3. Compile and run your code.

    The Amazon SQS queue is set as the dead-letter queue for the specified Amazon SNS subscription.

To configure a dead-letter queue for an Amazon SNS subscription using the AWS CLI

Before your begin this tutorial, make sure you complete the prerequisites.

  1. Install and configure the AWS CLI. For more information, see the AWS Command Line Interface User Guide.

  2. Use the following command.

    aws sns set-subscription-attributes \ --subscription-arn arn:aws:sns:us-east-2:123456789012:MyEndpoint:1234a567-bc89-012d-3e45-6fg7h890123i --attribute-name RedrivePolicy --attribute-value "{\"deadLetterTargetArn\": \"arn:aws:sqs:us-east-2:123456789012:MyDeadLetterQueue\"}"

To configure a dead-letter queue for an Amazon SNS subscription using AWS CloudFormation

Before your begin this tutorial, make sure you complete the prerequisites.

  1. Copy the following JSON code to a file named MyDeadLetterQueue.json.

    { "Resources": { "mySubscription": { "Type" : "AWS::SNS::Subscription", "Properties" : { "Protocol": "sqs", "Endpoint": "arn:aws:sqs:us-east-2:123456789012:MyEndpoint", "TopicArn": "arn:aws:sns:us-east-2:123456789012:MyTopic", "RedrivePolicy": { "deadLetterTargetArn": "arn:aws:sqs:us-east-2:123456789012:MyDeadLetterQueue" } } } } }
  2. Sign in to the AWS CloudFormation console.

  3. On the Select Template page, choose Upload a template to Amazon S3, choose your MyDeadLetterQueue.json file, and then choose Next.

  4. On the Specify Details page, enter MyDeadLetterQueue for Stack Name, and then choose Next.

  5. On the Options page, choose Next.

  6. On the Review page, choose Create.

    AWS CloudFormation begins to create the MyDeadLetterQueue stack and displays the CREATE_IN_PROGRESS status. When the process is complete, AWS CloudFormation displays the CREATE_COMPLETE status.