Skip to main content

Amazon Simple Notification Service (SNS) Integration

The Amazon SNS integration allows you to be notified when messages are sent to an Amazon SNS topic. Use this integration when you're sending custom SNS messages. If you're using an AWS service that sends its alerts via SNS, we might already have a dedicated integration for that. If so, check out these integrations: Amazon CloudWatch

Create SNS topic​

First, we configure the connection between SNS and Ready Five. In the AWS Console, open the Amazon SNS console and create a new topic. If you have an existing topic you'd prefer to use, you can skip this step.

SNS Topic Index

Choose a generic name, typically something describing the contents that go through the topic, not where the data comes from or where it's going (you probably don't want to include Ready Five in the name, as topics can have a nearly unlimited number of subscribers).

New SNS Topic Create SNS Topic

Create the Ready Five integration​

In your web browser, navigate to the "Integrations" tab in the team that should own this integration and click the "Add Integration" button.

Integration add button

For the integration type, click the "Add" button in the Amazon SNS box.

Add integration SNS type

Give the integration a name (or keep the default) and an optional description and click "Add".

The integration is now created, and you now have a URL on this screen that you'll need in a minute. Keep this tab open and open another.

Add the Ready Five integration as an SNS subscription​

Copy this URL and head back to the AWS SNS Console. From your SNS topic screen, click the "Create subscription" button.

SNS topic info SNS topic subscription create button

The Topic ARN should be pre-filled with your topic. If it isn't for some reason, search for it and select it. Choose "HTTPS" as the Protocol. Paste the URL provided on the Ready Five integration screen and click "Create subscription".

SNS subscription details form SNS subscription create button

Confirm the SNS subscription​

Amazon SNS subscriptions must be confirmed before messages will be published to the subscriber. Upon creating the subscription, a confirmation message is sent to the URL, which creates an incident in Ready Five.

Head over to the Ready Five incidents screen. You'll find a newly created incident in the Open / All tab if you're an account owner or administrator or in the Open / My Teams tab if you're a team administrator.

SNS confirmation incident triggered

Open this incident and scroll through its details until you find the "SubscribeURL" attribute.

SNS subscription subscribe URL

Click the URL to confirm this subscription. The confirmation screen displays some lovely XML. Though this may seem like an error at first glance, it's expected.

SNS subscription confirmation XML

Take another look at the subscription in the AWS console and it will show as confirmed.

SNS subscription confirmed

This confirmation means that any messages sent to this topic will be forwarded to the Ready Five integration specified in the subscription.

You can resolve the incident created by the subscription confirmation message.

SNS subscription confirmed

Publishing SNS messages​

Since this is a low-level SNS integration, we assume that you have some control over the incoming message so there is a particular message structure that we need to map your message to properly creating or updating an incident.

By default the SNS message's "Subject" is used as the title for the incident. You can override the incident title by specifying title as a message attribute as described below.

SNS allows specifying message attributes on each published message. These attributes are separate from the message body, and it's where Ready Five looks for these attributes.

Ready Five accepts the following message attributes to be set, and each must be of the String type. All attributes are optional.

action (optional): Can be one of TRIGGER, ACKNOWLEDGE, or RESOLVE. If no value is supplied or the value supplied is invalid, defaults to TRIGGER.

severity (optional): Can be one of SEV1, SEV2, SEV3, SEV4, or SEV5. If no value is supplied or the value supplied is invalid, defaults to SEV1. SEV1 is the highest, most critical severity. SEV5 is the lowest.

groupKey (optional): Specify a group key to aggregate multiple alerts into the same incident. Using this attribute allows you to post an initial message with the action set to TRIGGER, followed by subsequent messages with action set to ACKNOWLEDGE or RESOLVE to take action on the existing incident. Omitting this will create a new incident for all messages with the action TRIGGER and messages that specify ACKNOWLEDGE or RESOLVE will be suppressed.

title (optional): Specify any string in this attribute and it will be used as the incident title. Specifying this attribute takes precedence over setting the SNS message subject, unless this attribute is blank.

SNS provides at-least-once guarantees for messages being delivered to subscribers. We handle this potential for duplicates and guarantee exactly once delivery to your configured integration.

You can send any number of messages through the same SNS topic and can ensure proper grouping by using the groupKey message attribute described above.

Signature verification​

All messages from SNS contain a digital signature, allowing the recipient to verify that the message was actually created and sent by the SNS service. As a security measure, all messages received by an SNS integration or any integrations built on top of SNS always verify message signatures.

If a message is received by Ready Five to one of these integrations without a valid signature from Amazon, the title of any incident created by the message will be suffixed with " - Warning: unable to verify AWS signature, SNS message may be forged.".

Both SNS signature version 1 (SHA1) and signature version 2 (SHA256) messages are supported for automatic verification.