eliferjunior/aws-sns

AWS SNS

Amazon Simple Notification Service (SNS) is a fully managed pub/sub messaging service. Publishers send messages to topics, and subscribers receive them via SQS, Lambda, HTTP/S, email, SMS, or mobile push. It's the glue for fan-out architectures.

Core Concepts

• Topic — a logical channel for publishing messages
• Subscription — an endpoint subscribed to a topic (SQS, Lambda, HTTP, email, SMS)
• Message filtering — JSON policy to route only matching messages to a subscriber
• Fan-out — one message published, delivered to all subscribers simultaneously
• FIFO Topic — ordered, deduplicated delivery (pairs with FIFO SQS queues)

Topics

# Create a standard topic
aws sns create-topic --name order-events

# Create a FIFO topic
aws sns create-topic \
  --name order-events.fifo \
  --attributes FifoTopic=true,ContentBasedDeduplication=true

# List topics
aws sns list-topics --query 'Topics[].TopicArn' --output table

Subscriptions

# Subscribe an SQS queue to a topic
aws sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events \
  --protocol sqs \
  --notification-endpoint arn:aws:sqs:us-east-1:123456789:order-processing

# Subscribe a Lambda function
aws sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events \
  --protocol lambda \
  --notification-endpoint arn:aws:lambda:us-east-1:123456789:function:process-order

# Subscribe an HTTP endpoint
aws sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events \
  --protocol https \
  --notification-endpoint https://api.myapp.com/webhooks/orders

# Subscribe email (requires confirmation)
aws sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events \
  --protocol email \
  --notification-endpoint [email protected]

# List subscriptions for a topic
aws sns list-subscriptions-by-topic \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events

Publishing Messages

# Publish a message to a topic
aws sns publish \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events \
  --message '{"orderId":"12345","status":"completed","amount":99.99}' \
  --message-attributes '{
    "event_type": {"DataType":"String","StringValue":"order.completed"},
    "priority": {"DataType":"String","StringValue":"high"}
  }'

# Publish to FIFO topic
aws sns publish \
  --topic-arn arn:aws:sns:us-east-1:123456789:order-events.fifo \
  --message '{"orderId":"12345","status":"completed"}' \
  --message-group-id "customer-789" \
  --message-deduplication-id "order-12345-completed"

# Publish with different payloads per protocol
aws sns publish \
  --topic-arn arn:aws:sns:us-east-1:123456789:alerts \
  --message-structure json \
  --message '{
    "default": "Order 12345 completed",
    "email": "Your order #12345 has been completed. Thank you!",
    "sqs": "{\"orderId\":\"12345\",\"status\":\"completed\"}"
  }'

Message Filtering

# Set filter policy — subscriber only gets "order.completed" events
aws sns set-subscription-attributes \
  --subscription-arn arn:aws:sns:us-east-1:123456789:order-events:abc-123 \
  --attribute-name FilterPolicy \
  --attribute-value '{
    "event_type": ["order.completed"],
    "priority": ["high", "critical"]
  }'

# Filter on message body (not just attributes)
aws sns set-subscription-attributes \
  --subscription-arn arn:aws:sns:us-east-1:123456789:order-events:abc-123 \
  --attribute-name FilterPolicyScope \
  --attribute-value MessageBody

aws sns set-subscription-attributes \
  --subscription-arn arn:aws:sns:us-east-1:123456789:order-events:abc-123 \
  --attribute-name FilterPolicy \
  --attribute-value '{"status": ["completed"], "amount": [{"numeric": [">=", 100]}]}'

Fan-Out Pattern (SNS → SQS)

# Fan-out setup: one SNS topic publishing to multiple SQS queues
import boto3
import json

sns = boto3.client('sns')
sqs = boto3.client('sqs')

# Create topic
topic = sns.create_topic(Name='order-events')
topic_arn = topic['TopicArn']

# Create queues for different consumers
queues = ['order-fulfillment', 'order-analytics', 'order-notifications']
for queue_name in queues:
    queue = sqs.create_queue(QueueName=queue_name)
    queue_url = queue['QueueUrl']
    attrs = sqs.get_queue_attributes(QueueUrl=queue_url, AttributeNames=['QueueArn'])
    queue_arn = attrs['Attributes']['QueueArn']

    # Allow SNS to send to SQS
    policy = {
        "Statement": [{
            "Effect": "Allow",
            "Principal": {"Service": "sns.amazonaws.com"},
            "Action": "sqs:SendMessage",
            "Resource": queue_arn,
            "Condition": {"ArnEquals": {"aws:SourceArn": topic_arn}}
        }]
    }
    sqs.set_queue_attributes(QueueUrl=queue_url, Attributes={"Policy": json.dumps(policy)})

    # Subscribe
    sns.subscribe(TopicArn=topic_arn, Protocol='sqs', Endpoint=queue_arn)

Mobile Push

# Create platform application for FCM (Android)
aws sns create-platform-application \
  --name my-app-android \
  --platform GCM \
  --attributes PlatformCredential="YOUR_FCM_SERVER_KEY"

# Register a device token
aws sns create-platform-endpoint \
  --platform-application-arn arn:aws:sns:us-east-1:123456789:app/GCM/my-app-android \
  --token "device-token-from-fcm"

# Send push notification to a device
aws sns publish \
  --target-arn arn:aws:sns:us-east-1:123456789:endpoint/GCM/my-app-android/abc123 \
  --message '{"GCM":"{\"notification\":{\"title\":\"Order Shipped\",\"body\":\"Your order is on the way\"}}"}' \
  --message-structure json

Best Practices

• Use message filtering to avoid unnecessary processing at subscribers
• Pair SNS with SQS for reliable fan-out (SNS alone doesn't retry on failure)
• Use FIFO topics + FIFO queues when message ordering matters
• Set delivery retry policies for HTTP/S endpoints
• Enable CloudWatch logging on SNS topics for debugging
• Use message attributes for routing, keep the body for data
• Grant least-privilege access with topic policies