AWS SNS HTTP/S subscription, confirmation and publish example

29/01/2021 - AWS

When using Amazon Simple Notification Service (SNS) for "subscribe" and "publish" features, there is subscription confirmation step in between. After someone subscribes to an "endpoint", Amazon SNS will send a subscription confirmation message. If email "protocol" was used with an email address as the "endpoint" property, an email is sent. If http/https "protocol" was used with a URL as the "endpoint" property, a POST request is sent. In both cases, the message content will have SubscribeURL data. This URL has to be visited in order to confirm subscription otherwise when something is published, original subscription will be disregarded. A successful response (200 OK) of visited URL will be XML and contain SubscriptionArn and RequestId properties.


Example


I used https protocol and https://asd34hjfd.m.pipedream.net/ endpoint in my test. You could use email and an email address as protocol and endpoint respectively.


Subscription confirmation message content


This is what you will receive from Amazon.


{
  "headers": {
    "host": "asd34hjfd.m.pipedream.net",
    "x-amzn-trace-id": "Root=1-60146237-1bb8db87053a3fa237869185",
    "content-length": "697",
    "user-agent": "Amazon Simple Notification Service Agent",
    "accept-encoding": "gzip, deflate",
    "accept": "*/*",
    "content-type": "text/plain",
    "x-amz-sns-message-type": "SubscriptionConfirmation",
    "x-amz-sns-topic-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "x-amz-sns-subscription-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter:44980782-18b0-4596-aee3-144f3f47dedf"
  },
  "body": {
    "Type": "SubscriptionConfirmation",
    "MessageId": "718e57b1-076f-4d95-929e-99996c34209d",
    "TopicArn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "Message": "You have chosen to subscribe to the topic arn:aws:sns:eu-west-1:000000000000:newsletter.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
    "Timestamp": "2021-01-29T19:29:57.582Z",
    "SignatureVersion": "1",
    "Signature": "EXAMPLEpH+..",
    "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-0000000000000000000000.pem",
    "SubscribeURL": "http://localhost:4566/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:eu-west-1:000000000000:newsletter&Token=90a9c15d",
    "Token": "90a9c15d"
  },
  "inferred_body_type": "JSON",
  "method": "POST",
  "url": "https://asd34hjfd.m.pipedream.net/",
  "client_ip": "1.10.40.10",
  "query": {
    
  }
}

Publish message content


Once you confirmed subscription above, this is what your https://asd34hjfd.m.pipedream.net/ endpoint would receive as a POST request. I've published hello message.


{
  "headers": {
    "host": "asd34hjfd.m.pipedream.net",
    "x-amzn-trace-id": "Root=1-6014626e-0703d14767d4d65d2a957a97",
    "content-length": "363",
    "user-agent": "Amazon Simple Notification Service Agent",
    "accept-encoding": "gzip, deflate",
    "accept": "*/*",
    "content-type": "text/plain",
    "x-amz-sns-message-type": "Notification",
    "x-amz-sns-topic-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "x-amz-sns-subscription-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter:44980782-18b0-4596-aee3-144f3f47dedf"
  },
  "body": {
    "Type": "Notification",
    "MessageId": "7983a6d0-d1af-4846-977f-b14aa5e040a5",
    "TopicArn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "Message": "hello",
    "Timestamp": "2021-01-29T19:30:53.973Z",
    "SignatureVersion": "1",
    "Signature": "EXAMPLEpH+..",
    "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-0000000000000000000000.pem"
  },
  "inferred_body_type": "JSON",
  "method": "POST",
  "url": "https://asd34hjfd.m.pipedream.net/",
  "client_ip": "1.10.40.10",
  "query": {
    
  }
}

Test


Create a topic (you)


$ aws --profile localstack --endpoint-url http://localhost:4566 sns create-topic --name newsletter
{
    "TopicArn": "arn:aws:sns:eu-west-1:000000000000:newsletter"
}

Subscribe to a topic (client)


$ aws --profile localstack --endpoint-url http://localhost:4566 sns subscribe --topic-arn arn:aws:sns:eu-west-1:000000000000:newsletter --protocol https --notification-endpoint https://efs324vfd43.m.pipedream.net
{
    "SubscriptionArn": "arn:aws:sns:eu-west-1:000000000000:newsletter:43014665-f108-4176-96ef-121382da3776"
}

This is the subscription details.


$ aws --profile localstack --endpoint-url http://localhost:4566 sns list-subscriptions
{
    "Subscriptions": [
        {
            "SubscriptionArn": "arn:aws:sns:eu-west-1:000000000000:newsletter:43014665-f108-4176-96ef-121382da3776",
            "Owner": "",
            "Protocol": "https",
            "Endpoint": "https://efs324vfd43.m.pipedream.net",
            "TopicArn": "arn:aws:sns:eu-west-1:000000000000:newsletter"
        }
    ]
}

Confirm subscription (client)


This is what your endpoint will receive and you will have to visit SubscribeURL. Once visited, a 200 OK XML response will be returned as described above.


{
  "headers": {
    "host": "efs324vfd43.m.pipedream.net",
    "x-amzn-trace-id": "Root=1-60147dc0-45ac810e098a1f4a57c5a652",
    "content-length": "697",
    "user-agent": "Amazon Simple Notification Service Agent",
    "accept-encoding": "gzip, deflate",
    "accept": "*/*",
    "content-type": "text/plain",
    "x-amz-sns-message-type": "SubscriptionConfirmation",
    "x-amz-sns-topic-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "x-amz-sns-subscription-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter:43014665-f108-4176-96ef-121382da3776"
  },
  "body": {
    "Type": "SubscriptionConfirmation",
    "MessageId": "97c3152b-7a51-4cc1-85fb-a05c5e00bac6",
    "TopicArn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "Message": "You have chosen to subscribe to the topic arn:aws:sns:eu-west-1:000000000000:newsletter.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
    "Timestamp": "2021-01-29T21:27:27.739Z",
    "SignatureVersion": "1",
    "Signature": "EXAMPLEpH+..",
    "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-0000000000000000000000.pem",
    "SubscribeURL": "http://localhost:4566/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:eu-west-1:000000000000:newsletter&Token=555f40e4",
    "Token": "555f40e4"
  },
  "inferred_body_type": "JSON",
  "method": "POST",
  "url": "https://efs324vfd43.m.pipedream.net/",
  "client_ip": "1.15.10.10",
  "query": {
    
  }
}

Publish message to a topic (you)


$ aws --profile localstack --endpoint-url http://localhost:4566 sns publish --topic-arn arn:aws:sns:eu-west-1:000000000000:newsletter --message "hello"
{
    "MessageId": "b774ac11-acc9-4c28-b0dd-a4aeeaceb58d"
}

This is the request your endpoint will receive.


{
  "headers": {
    "host": "efs324vfd43.m.pipedream.net",
    "x-amzn-trace-id": "Root=1-60147ee8-4d11aef729aa6bb6192fbcfc",
    "content-length": "363",
    "user-agent": "Amazon Simple Notification Service Agent",
    "accept-encoding": "gzip, deflate",
    "accept": "*/*",
    "content-type": "text/plain",
    "x-amz-sns-message-type": "Notification",
    "x-amz-sns-topic-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "x-amz-sns-subscription-arn": "arn:aws:sns:eu-west-1:000000000000:newsletter:43014665-f108-4176-96ef-121382da3776"
  },
  "body": {
    "Type": "Notification",
    "MessageId": "b774ac11-acc9-4c28-b0dd-a4aeeaceb58d",
    "TopicArn": "arn:aws:sns:eu-west-1:000000000000:newsletter",
    "Message": "hello",
    "Timestamp": "2021-01-29T21:32:23.540Z",
    "SignatureVersion": "1",
    "Signature": "EXAMPLEpH+..",
    "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-0000000000000000000000.pem"
  },
  "inferred_body_type": "JSON",
  "method": "POST",
  "url": "https://efs324vfd43.m.pipedream.net/",
  "client_ip": "1.15.10.10",
  "query": {
    
  }
}