AWS::SNS::Subscription

Syntax Properties Return values Examples

The AWS::SNS::Subscription resource subscribes an endpoint to an Amazon SNS topic. For a subscription to be created, the owner of the endpoint must` confirm the subscription.

To declare this entity in your AWS CloudFormation template, use the following syntax:


{
  "Type" : "AWS::SNS::Subscription",
  "Properties" : {
      "DeliveryPolicy" : Json,
      "Endpoint" : String,
      "FilterPolicy" : Json,
      "FilterPolicyScope" : String,
      "Protocol" : String,
      "RawMessageDelivery" : Boolean,
      "RedrivePolicy" : Json,
      "Region" : String,
      "ReplayPolicy" : Json,
      "SubscriptionRoleArn" : String,
      "TopicArn" : String
    }
}


Type: AWS::SNS::Subscription
Properties:
  DeliveryPolicy: Json
  Endpoint: String
  FilterPolicy: Json
  FilterPolicyScope: String
  Protocol: String
  RawMessageDelivery: Boolean
  RedrivePolicy: Json
  Region: String
  ReplayPolicy: Json
  SubscriptionRoleArn: String
  TopicArn: String

DeliveryPolicy

The delivery policy JSON assigned to the subscription. Enables the subscriber to define the message delivery retry strategy in the case of an HTTP/S endpoint subscribed to the topic. For more information, see GetSubscriptionAttributes in the Amazon SNS API Reference and Message delivery retries in the Amazon SNS Developer Guide.

Required: No

Type: Json

Update requires: No interruption

Endpoint

The subscription's endpoint. The endpoint value depends on the protocol that you specify. For more information, see the Endpoint parameter of the Subscribe action in the Amazon SNS API Reference.

Required: No

Type: String

Update requires: Replacement

FilterPolicy

The filter policy JSON assigned to the subscription. Enables the subscriber to filter out unwanted messages. For more information, see GetSubscriptionAttributes in the Amazon SNS API Reference and Message filtering in the Amazon SNS Developer Guide.

Required: No

Type: Json

Update requires: No interruption

FilterPolicyScope

This attribute lets you choose the filtering scope by using one of the following string value types:

MessageAttributes (default) - The filter is applied on the message attributes.
MessageBody - The filter is applied on the message body.

Note

Null is not a valid value for FilterPolicyScope. To delete a filter policy, delete the FilterPolicy property but keep FilterPolicyScope property as is.

Required: No

Type: String

Update requires: No interruption

Protocol

The subscription's protocol. For more information, see the Protocol parameter of the Subscribe action in the Amazon SNS API Reference.

Required: Yes

Type: String

Update requires: Replacement

RawMessageDelivery

When set to true, enables raw message delivery. Raw messages don't contain any JSON formatting and can be sent to Amazon SQS and HTTP/S endpoints. For more information, see GetSubscriptionAttributes in the Amazon SNS API Reference.

Required: No

Type: Boolean

Update requires: No interruption

RedrivePolicy

When specified, sends undeliverable messages to the specified Amazon SQS dead-letter queue. Messages that can't be delivered due to client errors (for example, when the subscribed endpoint is unreachable) or server errors (for example, when the service that powers the subscribed endpoint becomes unavailable) are held in the dead-letter queue for further analysis or reprocessing.

For more information about the redrive policy and dead-letter queues, see Amazon SQS dead-letter queues in the Amazon SQS Developer Guide.

Required: No

Type: Json

Update requires: No interruption

Region

For cross-region subscriptions, the region in which the topic resides.

If no region is specified, AWS CloudFormation uses the region of the caller as the default.

If you perform an update operation that only updates the Region property of a AWS::SNS::Subscription resource, that operation will fail unless you are either:

Updating the Region from NULL to the caller region.
Updating the Region from the caller region to NULL.

Required: No

Type: String

Update requires: Some interruptions

ReplayPolicy

Specifies whether Amazon SNS resends the notification to the subscription when a message's attribute changes.

Required: No

Type: Json

Update requires: No interruption

SubscriptionRoleArn

This property applies only to Amazon Data Firehose delivery stream subscriptions. Specify the ARN of the IAM role that has the following:

Permission to write to the Amazon Data Firehose delivery stream
Amazon SNS listed as a trusted entity

Specifying a valid ARN for this attribute is required for Firehose delivery stream subscriptions. For more information, see Fanout to Amazon Data Firehose delivery streams in the Amazon SNS Developer Guide.

Required: No

Type: String

Update requires: No interruption

TopicArn

The ARN of the topic to subscribe to.

Required: Yes

Type: String

Update requires: Replacement

When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the subscription's logical name. This attribute allows you to reference the logical name of the subscription resource within the CloudFormation template.

For example, if you have a subscription resource named 'MySubscription', you can use '!Ref MySubscription' to refer to its logical name in other parts of the CloudFormation template.

For more information about using the Ref function, see Ref.

The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.

Arn: Returns the ARN of the subscription created by the AWS::SNS::Subscription resource.

Create a subscription with mandatory attributes
Create a subscription with optional attributes

The following example creates a subscription with only an endpoint, protocol, and topic ARN.


"MySubscription" : {
  "Type" : "AWS::SNS::Subscription",
  "Properties" : {
    "Endpoint" : "test@example.com",
    "Protocol" : "email",
    "TopicArn" : { "Ref" : "MySNSTopic" }
  }
}


MySubscription:
  Type: AWS::SNS::Subscription
  Properties:
    Endpoint: test@example.com
    Protocol: email
    TopicArn: !Ref 'MySNSTopic'

The following example creates a subscription with a filter policy, delivery policy, and raw message delivery enabled.

Note

You can set subscription attributes only on standalone Amazon SNS subscriptions (not on subscriptions nested in topics).


AWSTemplateFormatVersion: 2010-09-09
Resources:
  CarSalesTopic:
    Type: 'AWS::SNS::Topic'
  ERPSubscription:
    Type: 'AWS::SNS::Subscription'
    Properties:
      TopicArn: !Ref CarSalesTopic
      Endpoint: !GetAtt 
        - ERPIntegrationQueue
        - Arn
      Protocol: sqs
      RawMessageDelivery: 'true'
  CRMSubscription:
    Type: 'AWS::SNS::Subscription'
    Properties:
      TopicArn: !Ref CarSalesTopic
      Endpoint: !GetAtt 
        - CRMIntegrationQueue
        - Arn
      Protocol: sqs
      RawMessageDelivery: 'true'
      FilterPolicy:
        buyer-class:
          - vip
  SCMSubscription:
    Type: 'AWS::SNS::Subscription'
    Properties:
      TopicArn: !Ref CarSalesTopic
      Endpoint: !Ref myHttpEndpoint
      Protocol: https
      DeliveryPolicy:
        healthyRetryPolicy:
          numRetries: 20
          minDelayTarget: 10
          maxDelayTarget: 30
          numMinDelayRetries: 3
          numMaxDelayRetries: 17
          numNoDelayRetries: 0
          backoffFunction: exponential
  ERPIntegrationQueue:
    Type: 'AWS::SQS::Queue'
    Properties: {}
  CRMIntegrationQueue:
    Type: 'AWS::SQS::Queue'
    Properties: {}
Parameters:
  myHttpEndpoint:
    Type: String


{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
        "CarSalesTopic": {
            "Type": "AWS::SNS::Topic"
        },
        "ERPSubscription": {
            "Type": "AWS::SNS::Subscription",
            "Properties": {
                "TopicArn": {
                    "Ref": "CarSalesTopic"
                },
                "Endpoint": {
                    "Fn::GetAtt": ["ERPIntegrationQueue", "Arn"]
                },
                "Protocol": "sqs",
                "RawMessageDelivery": "true"
            }
        },
        "CRMSubscription": {
            "Type": "AWS::SNS::Subscription",
            "Properties": {
                "TopicArn": {
                    "Ref": "CarSalesTopic"
                },
                "Endpoint": {
                    "Fn::GetAtt": ["CRMIntegrationQueue", "Arn"]
                },
                "Protocol": "sqs",
                "RawMessageDelivery": "true",
                "FilterPolicy": {
                    "buyer-class": [
                        "vip"
                    ]
                }
            }
        },
        "SCMSubscription": {
            "Type": "AWS::SNS::Subscription",
            "Properties": {
                "TopicArn": {
                    "Ref": "CarSalesTopic"
                },
                "Endpoint": {
                    "Ref": "myHttpEndpoint"
                },
                "Protocol": "https",
                "DeliveryPolicy": {
                    "healthyRetryPolicy": {
                        "numRetries": 20,
                        "minDelayTarget": 10,
                        "maxDelayTarget": 30,
                        "numMinDelayRetries": 3,
                        "numMaxDelayRetries": 17,
                        "numNoDelayRetries": 0,
                        "backoffFunction": "exponential"
                    }
                }
            }
        },
        "ERPIntegrationQueue": {
            "Type": "AWS::SQS::Queue",
            "Properties": {}
        },
        "CRMIntegrationQueue": {
            "Type": "AWS::SQS::Queue",
            "Properties": {}
        }
    },
    "Parameters": {
        "myHttpEndpoint": {
            "Type": "String"
        }
    }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Amazon Simple Notification Service

AWS::SNS::Topic

Syntax

JSON

YAML

Properties

Note

Return values

Ref

Fn::GetAtt

Examples

Create a subscription with mandatory attributes

JSON

YAML

Create a subscription with optional attributes

Note

YAML

JSON