1 | # CDK Construct Library for Amazon Simple Notification Service Subscriptions
|
2 |
|
3 |
|
4 | ---
|
5 |
|
6 | ![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)
|
7 |
|
8 | ---
|
9 |
|
10 |
|
11 |
|
12 | This library provides constructs for adding subscriptions to an Amazon SNS topic.
|
13 | Subscriptions can be added by calling the `.addSubscription(...)` method on the topic.
|
14 |
|
15 | ## Subscriptions
|
16 |
|
17 | Subscriptions can be added to the following endpoints:
|
18 |
|
19 | * HTTPS
|
20 | * Amazon SQS
|
21 | * AWS Lambda
|
22 | * Email
|
23 | * SMS
|
24 |
|
25 | Subscriptions to Amazon SQS and AWS Lambda can be added on topics across regions.
|
26 |
|
27 | Create an Amazon SNS Topic to add subscriptions.
|
28 |
|
29 | ```ts
|
30 | const myTopic = new sns.Topic(this, 'MyTopic');
|
31 | ```
|
32 |
|
33 | ### HTTPS
|
34 |
|
35 | Add an HTTP or HTTPS Subscription to your topic:
|
36 |
|
37 | ```ts
|
38 | const myTopic = new sns.Topic(this, 'MyTopic');
|
39 |
|
40 | myTopic.addSubscription(new subscriptions.UrlSubscription('https://foobar.com/'));
|
41 | ```
|
42 |
|
43 | The URL being subscribed can also be [tokens](https://docs.aws.amazon.com/cdk/latest/guide/tokens.html), that resolve
|
44 | to a URL during deployment. A typical use case is when the URL is passed in as a [CloudFormation
|
45 | parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html). The
|
46 | following code defines a CloudFormation parameter and uses it in a URL subscription.
|
47 |
|
48 | ```ts
|
49 | const myTopic = new sns.Topic(this, 'MyTopic');
|
50 | const url = new CfnParameter(this, 'url-param');
|
51 |
|
52 | myTopic.addSubscription(new subscriptions.UrlSubscription(url.valueAsString));
|
53 | ```
|
54 |
|
55 | ### Amazon SQS
|
56 |
|
57 | Subscribe a queue to your topic:
|
58 |
|
59 | ```ts
|
60 | const myQueue = new sqs.Queue(this, 'MyQueue');
|
61 | const myTopic = new sns.Topic(this, 'MyTopic');
|
62 |
|
63 | myTopic.addSubscription(new subscriptions.SqsSubscription(myQueue));
|
64 | ```
|
65 |
|
66 | KMS key permissions will automatically be granted to SNS when a subscription is made to
|
67 | an encrypted queue.
|
68 |
|
69 | Note that subscriptions of queues in different accounts need to be manually confirmed by
|
70 | reading the initial message from the queue and visiting the link found in it.
|
71 |
|
72 | ### AWS Lambda
|
73 |
|
74 | Subscribe an AWS Lambda function to your topic:
|
75 |
|
76 | ```ts
|
77 | import * as lambda from '@aws-cdk/aws-lambda';
|
78 |
|
79 | const myTopic = new sns.Topic(this, 'myTopic');
|
80 | declare const myFunction: lambda.Function;
|
81 | myTopic.addSubscription(new subscriptions.LambdaSubscription(myFunction));
|
82 | ```
|
83 |
|
84 | ### Email
|
85 |
|
86 | Subscribe an email address to your topic:
|
87 |
|
88 | ```ts
|
89 | const myTopic = new sns.Topic(this, 'MyTopic');
|
90 | myTopic.addSubscription(new subscriptions.EmailSubscription('foo@bar.com'));
|
91 | ```
|
92 |
|
93 | The email being subscribed can also be [tokens](https://docs.aws.amazon.com/cdk/latest/guide/tokens.html), that resolve
|
94 | to an email address during deployment. A typical use case is when the email address is passed in as a [CloudFormation
|
95 | parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html). The
|
96 | following code defines a CloudFormation parameter and uses it in an email subscription.
|
97 |
|
98 | ```ts
|
99 | const myTopic = new sns.Topic(this, 'Topic');
|
100 | const emailAddress = new CfnParameter(this, 'email-param');
|
101 |
|
102 | myTopic.addSubscription(new subscriptions.EmailSubscription(emailAddress.valueAsString));
|
103 | ```
|
104 |
|
105 | Note that email subscriptions require confirmation by visiting the link sent to the
|
106 | email address.
|
107 |
|
108 | ### SMS
|
109 |
|
110 | Subscribe an sms number to your topic:
|
111 |
|
112 | ```ts
|
113 | const myTopic = new sns.Topic(this, 'Topic');
|
114 |
|
115 | myTopic.addSubscription(new subscriptions.SmsSubscription('+15551231234'));
|
116 | ```
|
117 |
|
118 | The number being subscribed can also be [tokens](https://docs.aws.amazon.com/cdk/latest/guide/tokens.html), that resolve
|
119 | to a number during deployment. A typical use case is when the number is passed in as a [CloudFormation
|
120 | parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html). The
|
121 | following code defines a CloudFormation parameter and uses it in an sms subscription.
|
122 |
|
123 | ```ts
|
124 | const myTopic = new sns.Topic(this, 'Topic');
|
125 | const smsNumber = new CfnParameter(this, 'sms-param');
|
126 |
|
127 | myTopic.addSubscription(new subscriptions.SmsSubscription(smsNumber.valueAsString));
|
128 | ```
|