A Stacktape SNS topic is a fully managed, serverless pub/sub messaging service built on Amazon SNS. Publish a message once and deliver it to many subscribers — Lambda functions, SQS queues, email addresses, SMS numbers, or HTTP endpoints. You pay per publish with no upfront cost and no infrastructure to manage.
SNS is pay-per-publish with no minimum fee. The first 1 million publishes per month are in the AWS Free Tier. SMS and email deliveries have separate per-message charges. Check current AWS SNS pricing for regional details.
When to use
Use an SNS topic when a single event needs to trigger multiple independent actions. Common scenarios:
- Fan-out to multiple consumers — an order-placed event triggers email confirmation, inventory update, and analytics simultaneously. Each subscriber receives its own copy of the message.
- Cross-service notifications — notify multiple Lambda functions or SQS queues from a single publish call, without the producer needing to know about each consumer.
- Alert distribution — push notifications to email, SMS, or HTTP webhooks for operational events, user notifications, or system alerts.
- Decouple publishers from subscribers — the publisher sends to one topic; subscribers are added or removed independently without changing the publisher.
When NOT to use
- Single consumer processing — if only one service processes each message, use an SQS queue directly. SNS adds overhead when there is only one subscriber.
- Message retention and replay — SNS does not store messages. If a subscriber is offline when a message is published, that message is lost after delivery retries are exhausted. For durable, replayable streams, use a Kinesis stream.
- Complex event routing — if you need content-based routing with rich pattern matching beyond simple attribute filters, use an EventBridge event bus.
- Request-response — SNS is one-way. If your caller needs a synchronous response, invoke the downstream service directly or use an HTTP API Gateway.
Basic example
An SNS topic has no required properties. Because fifoEnabled defaults to false, omitting all properties creates a standard topic. In Stacktape, Lambda subscriptions are the documented integration path, configured using the SnsIntegration trigger (type: 'sns') on the Lambda function — see SNS triggers. For other subscription protocols not modeled by Stacktape, you can use cloudformationResources as a raw CloudFormation escape hatch.
Standard vs FIFO topics
Stacktape SNS topics support two modes: standard (default) and FIFO. The choice affects delivery guarantees, subscriber types, and throughput.
| Standard | FIFO | |
|---|---|---|
| Ordering | Best-effort | Strict within each message group |
| Delivery | At-least-once (rare duplicates possible) | Exactly-once |
| Subscriber types | Lambda, SQS, email, SMS, HTTP | FIFO SQS queues only |
| Throughput | Nearly unlimited | ~300 publishes/s (3,000 with batching) |
| Use cases | Notifications, alerts, general fan-out | Financial transactions, sequential workflows |
Standard topics are the right choice for most workloads. Use FIFO only when message ordering or exactly-once delivery is a hard requirement, and your subscribers are all FIFO SQS queues.
FIFO topic
Set fifoEnabled: true to create a FIFO topic. FIFO topics require deduplication — either enable contentBasedDeduplication (SNS uses a SHA-256 hash of the message body within a 5-minute window) or provide a MessageDeduplicationId on each publish. When publishing, you must also include a MessageGroupId to define the ordering scope — messages within the same group are delivered in strict order.
SMS display name
Set smsDisplayName to customize the sender name shown on SMS messages (max 11 characters). SMS is useful for transactional alerts or OTP flows where the recipient is a phone number rather than a service endpoint. SMS carries separate per-message charges that vary by destination country, and new AWS accounts start in an SMS sandbox that requires individual phone number verification before sending. Most teams skip SMS in favor of email or webhook notifications unless the use case specifically requires it. Because FIFO topics can only deliver to FIFO SQS queues, smsDisplayName is only relevant for standard topics.
Fan-out pattern
SNS fan-out delivers each published message to every subscriber independently. In Stacktape, the most direct fan-out uses multiple Lambda functions, each subscribing to the same topic via an SNS trigger. Each function receives its own copy of every message and processes it independently — the publisher does not need to know how many subscribers exist.
This example shows a single orderEvents topic with two independent subscribers: one sends email confirmations, the other records analytics. Publishing one message triggers both functions simultaneously.
Subscribing a Lambda function
A Lambda function can subscribe to an SNS topic using an SNS trigger. When a message is published, AWS invokes the function with the message payload. Configure this using an SNS event on the Lambda function — not on the topic itself.
Key settings on the trigger:
snsTopicName— reference a topic in the same Stacktape config. UsesnsTopicArnfor an external topic not managed by your stack. Specify exactly one.filterPolicy— filter messages by attributes so only relevant ones trigger the function. Uses SNS subscription filter policy syntax.onDeliveryFailure— route failed deliveries to an SQS queue for inspection. Reference a queue bysqsQueueName(same stack) orsqsQueueArn(external).
The Lambda handler receives the message in the Records array. Each record wraps the original message inside Sns.Message:
Connecting to other resources
Workloads that support connectTo, such as Lambda functions, web services, worker services, and multi-container workloads, can connect to an SNS topic. For an SnsTopic, connectTo grants publish and subscribe permissions and injects ARN and NAME environment variables.
For a topic named notifications, the injected environment variables are:
| Environment variable | Description |
|---|---|
STP_NOTIFICATIONS_ARN | The topic's Amazon Resource Name (use this with the AWS SDK to publish messages) |
STP_NOTIFICATIONS_NAME | The topic name |
For more details on connectTo, see Connecting resources.
Publishing a message from the connected Lambda function:
Examples
Lambda fan-out
A single SNS topic with two independent Lambda subscribers. Publishing one message triggers both functions simultaneously — one sends email confirmations, the other records analytics. Each function processes its own copy of the message independently.
Publishing from a connected Lambda
A Lambda function connected to an SNS topic via connectTo receives the STP_ALERTS_ARN and STP_ALERTS_NAME environment variables along with IAM permissions to publish. The function uses the AWS SDK to publish messages to the topic.
The handler publishes a message using the injected STP_ALERTS_ARN environment variable:
Referenceable parameters
SNS topic parameters can be referenced in your config using $ResourceParam. For a topic named notifications:
| Parameter | Example usage | Description |
|---|---|---|
arn | $ResourceParam('notifications', 'arn') | The topic's Amazon Resource Name |
name | $ResourceParam('notifications', 'name') | The topic name |
API Reference
SnsTopicPropsSNS Topic FAQ
When should I use an SNS topic vs an SQS queue?
Use an SNS topic when you need fan-out — multiple subscribers each receiving a copy of every message. Use an SQS queue when you have one consumer processing messages at its own pace. A common pattern combines both: SNS fans out to multiple SQS queues, giving each consumer its own buffer and independent retry behavior.
How does Amazon SNS pricing work?
SNS is pay-per-publish with no minimum fee — the first 1 million publishes per month are in the AWS Free Tier, and after that you pay per million publishes. SMS and email deliveries carry separate per-message charges that vary by destination country, so they cost more than fanning out to Lambda or SQS subscribers. Check current AWS SNS pricing for exact regional rates.
What is the maximum message size for SNS?
The maximum SNS message size is 256 KB. For larger payloads, store the data in an S3 bucket and include the S3 key in the SNS message body. Both standard and FIFO topics share this 256 KB limit.
How do I filter messages so subscribers only receive relevant ones?
Use filterPolicy on the SNS trigger to filter messages by their attributes. Only messages whose attributes match the filter policy are delivered to that subscriber. This reduces unnecessary Lambda invocations and processing costs. For richer content-based routing with nested pattern matching, consider an EventBridge event bus.
Can I use SNS with container services?
Yes. Use connectTo on a web service, worker service, or multi-container workload to get SNS permissions and the topic ARN injected as environment variables. Your container publishes messages using the AWS SDK. For subscribing containers to SNS messages, route them through an SQS queue and poll from the container.
What happens if a subscriber is offline when a message is published?
For Lambda subscribers, Amazon SNS retries delivery with exponential backoff. For SQS and HTTP/S subscribers, Amazon SNS follows its delivery retry policy — retrying over a period of time before giving up. SNS does not store messages, so if all retries fail the message is lost. For Stacktape SNS triggers on Lambda functions, you can configure onDeliveryFailure to send messages that fail delivery to an SQS queue for later inspection. If you need durable, replayable delivery, route the topic through an SQS queue or use a Kinesis stream instead.