Amazon SNS Component

Manage subscriptions, topics, and messages within Amazon (AWS) SNS

Component key: aws-sns

Description

Amazon SNS is a service for both application-to-application (A2A) and application-to-person (A2P) communication. The Amazon SNS component allows you to interact with an SNS Topic.

Connections

An AWS IAM access key pair is required to interact with Amazon SNS. Make sure that the key pair you generate in AWS has proper permissions to the SNS resources you want to access. Read about Amazon SNS IAM policies in the AWS docs.

AWS Role ARN

To enable the IAM role authentication begin by logging into the AWS Console and navigate to Identity and Access Management (IAM).

To create a user and generate credentials:

Navigate to Users and select Create User.

Provide a User name and check the box providing them user access to the AWS Managment Console if needed.
Once completed with the User creation, copy the ARN provided in the summary for a later step.

To obtain the ARN for an existing User, click on the designated username from the Users page and the ARN will be provided in the summary section.
From the summary section, select Create access key

Select Third-party service as the access key type and select next.
Set a description and select create access key.
Copy the Access Key and Secret access key and enter those into the connection configuration of your integration along with the ARN.

To create and assign a user a role:

Navigate to Roles and select Create Role.

Select Custom Trust Policy for the Trusted entity types
Copy the following statement into the statement console. Making sure to replace the ARN with the user's actual ARN from the previous section

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "ARN"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

When adding permissions provide the AmazonSNSFullAccess permission
Complete remaining steps and select Create Role

Triggers

Subscription Trigger

Confirm subscription and unsubscribe requests and validate SNS messages | key: subscriptionTrigger

Amazon SNS can be configured to send notification to an HTTPS endpoint. To point SNS notifications towards your integration, identify your integration's webhook URL, and subscribe that URL to an SNS topic. Once a subscription has been created, new messages sent to your SNS topic will be sent to your Prismatic instance via its webhook URL.

Messages from SNS take one of three forms: Subscription Confirmation, Unsubscribe Confirmation or Notification. If a subscription or unsubscribe message is received, this trigger automatically handles the subscription confirmation process. This process lets Amazon SNS know that your instance is ready to receive and process notifications.

Depending on what type of message is received, the trigger will then follow a "Subscribe", "Unsubscribe" or "Notification" branch. These branches make it so you can configure additional steps that execute (e.g. you can alert your team via Slack that a subscription has been confirmed). "Subscribe" and "Unsubscribe" branches can be left blank if you don't have any additional steps you'd like to run once a subscription has been confirmed - you will likely only fill in steps under the "Notification" branch.

In addition to confirming subscriptions, this trigger verifies the signature of messages that come in, so you know they originated from Amazon.

Testing must be done through SNS

Because of signature verification, testing of integrations with this trigger must be done using Amazon SNS. Tests from the integration designer, or from curl or another HTTP client will fail since you can't spoof Amazon's message signature.

When a "Notification" message comes in, and it is a JSON string, you can optionally choose to parse the JSON using the "Parse Message" input. Note that if the incoming message is not valid JSON, the trigger will throw an error when "Parse Message" is set to true.

Output Example Payload

{
  "payload": {
    "headers": {
      "x-amz-sns-message-type": "Notification",
      "x-amz-sns-message-id": "da41e39f-ea4d-435a-b922-c6aae3915ebe",
      "x-amz-sns-topic-arn": "arn:aws:sns:us-west-2:123456789012:MyTopic",
      "x-amz-sns-subscription-arn": "arn:aws:sns:us-west-2:123456789012:MyTopic:2bcfbf39-05c3-41de-beaa-fcfcc21c8f55",
      "Content-Length": "761",
      "Content-Type": "text/plain; charset=UTF-8",
      "Host": "ec2-50-17-44-49.compute-1.amazonaws.com",
      "Connection": "Keep-Alive",
      "User-Agent": "Amazon Simple Notification Service Agent"
    },
    "queryParameters": {},
    "rawBody": {
      "data": {}
    },
    "webhookUrls": {},
    "webhookApiKeys": {},
    "customer": {
      "externalId": "abc-123",
      "name": "Example Corp",
      "id": "exampleId"
    },
    "body": {
      "data": {
        "Type": "Notification",
        "MessageId": "da41e39f-ea4d-435a-b922-c6aae3915ebe",
        "TopicArn": "arn:aws:sns:us-west-2:123456789012:MyTopic",
        "Subject": "test",
        "Message": "test message",
        "Timestamp": "2012-04-25T21:49:25.719Z",
        "SignatureVersion": "1",
        "Signature": "EXAMPLElDMXvB8r9R83tGoNn0ecwd5UjllzsvSvbItzfaMpN2nk5HVSw7XnOn/49IkxDKz8YrlH2qJXj2iZB0Zo2O71c4qQk1fMUDi3LGpij7RCW7AW9vYYsSqIKRnFS94ilu7NFhUzLiieYr4BKHpdTmdD6c0esKEYBpabxDSc=",
        "SigningCertURL": "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem",
        "UnsubscribeURL": "https://sns.us-west-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-west-2:123456789012:MyTopic:2bcfbf39-05c3-41de-beaa-fcfcc21c8f55"
      }
    },
    "executionId": "",
    "instance": {
      "id": "example",
      "name": "exampleName"
    },
    "pathFragment": "example",
    "invokeUrl": "Url",
    "user": {
      "email": "email@email.test",
      "externalId": "externalId",
      "id": "123",
      "name": "name"
    }
  },
  "branch": "Notification"
}

Actions

Create Topic

Create an Amazon SNS Topic | key: createTopic

Output Example Payload

{
  "data": {
    "TopicArn": "arn:aws:Example Topic Arn"
  }
}

Delete Topic

Delete an Amazon SNS Topic | key: deleteTopic

Get Topic Attributes

Retrieves the attributes of an Amazon SNS Topic. | key: getTopicAttributes

Output Example Payload

{
  "data": {
    "Attributes": {
      "Policy": "Example Policy",
      "Owner": "0123456789000",
      "topicArn": "arn:aws:sns:us-east-2:123456789012:MyExampleTopic",
      "SubscriptionsPending": "1",
      "EffectiveDeliveryPolicy": "Example Delivery Policy",
      "SubscriptionsConfirmed": "5",
      "DisplayName": "Example Display Name",
      "SubscriptionsDeleted": "5"
    }
  }
}

List Opt Out Numbers

Create an Amazon SNS Topic | key: listOptOutNumbers

Output Example Payload

{
  "data": {
    "phoneNumbers": [
      "15556164096",
      "18980994152",
      "18008988422"
    ]
  }
}

List Subscriptions

Retrieve the subscriptions of an Amazon SNS Topic | key: listSubscriptions

Output Example Payload

{
  "data": {
    "Subscriptions": [
      {
        "SubscriptionArn": "arn:aws:sns:us-east-2:123456789012:MyExampleTopic:00000000-00000000-00000000-00000000",
        "Owner": "0123456789000",
        "Protocol": "https",
        "Endpoint": "https://example.com/",
        "TopicArn": "arn:aws:sns:us-east-2:123456789012:MyExampleTopic"
      },
      {
        "SubscriptionArn": "PendingConfirmation",
        "Owner": "0123456789000",
        "Protocol": "email",
        "Endpoint": "admin@example.com",
        "TopicArn": "arn:aws:sns:us-east-2:123456789012:MyExampleTopic"
      }
    ]
  }
}

List Topics

List available Amazon SNS Topics | key: listTopics

Output Example Payload

{
  "data": {
    "Topics": [
      {
        "TopicArn": "arn:aws:Example Topic Arn"
      }
    ]
  }
}

Publish Batch Messages

Publishes up to ten messages to the specified Amazon SNS Topic | key: publishBatchMessages

Output Example Payload

{
  "data": {
    "$metadata": {
      "httpStatusCode": 200,
      "requestId": "3df5ab1c-8e8a-426f-a2d1-bd7a39ef8651",
      "attempts": 1,
      "totalRetryDelay": 0
    },
    "Successful": [
      {
        "Id": "2",
        "MessageId": "6d1a92c3-77bc-49a5-bf62-1f047c34f9e7"
      }
    ],
    "Failed": []
  }
}

Publish Message

Publish a message to an Amazon SNS Topic | key: publishMessage

Output Example Payload

{
  "data": {
    "MessageId": "00000000-00000000-00000000-00000000"
  }
}

Publish SMS

Publish an SMS message to an Amazon SNS Topic | key: publishSms

Output Example Payload

{
  "data": {
    "MessageId": "00000000-00000000-00000000-00000000"
  }
}

Subscribe to an Amazon SNS Topic | key: subscribe

Output Example Payload

{
  "data": {
    "SubscriptionArn": "arn:aws:sns:us-east-2:123456789012:MyExampleTopic:00000000-00000000-00000000-00000000"
  }
}

Unsubscribe from a Topic

Unsubscribe from an Amazon SNS Topic | key: unsubscribe

Manage subscriptions, topics, and messages within Amazon (AWS) SNS

Description​

Connections​

AWS SNS Access Key and Secret​

AWS Role ARN​

Triggers​

Subscription Trigger​

Output Example Payload​

Actions​

Create Topic​

Output Example Payload​

Delete Topic​

Get Topic Attributes​

Output Example Payload​

List Opt Out Numbers​

Output Example Payload​

List Subscriptions​

Output Example Payload​

List Topics​

Output Example Payload​

Publish Batch Messages​

Output Example Payload​

Publish Message​

Output Example Payload​

Publish SMS​

Output Example Payload​

Subscribe to Topic​

Output Example Payload​

Unsubscribe from a Topic​

Description

Connections

AWS SNS Access Key and Secret

AWS Role ARN

Triggers

Subscription Trigger

Output Example Payload

Actions

Create Topic

Output Example Payload

Delete Topic

Get Topic Attributes

Output Example Payload

List Opt Out Numbers

Output Example Payload

List Subscriptions

Output Example Payload

List Topics

Output Example Payload

Publish Batch Messages

Output Example Payload

Publish Message

Output Example Payload

Publish SMS

Output Example Payload

Subscribe to Topic

Output Example Payload

Unsubscribe from a Topic