Skip to main content

​
Overview

The AWS SNS integration allows Rootly to treat Amazon Simple Notification Service (SNS) messages as a native alert source. Rootly subscribes to an SNS topic using an HTTPS webhook endpoint and processes SNS Notification messages that contain a supported Rootly alert payload. Unlike AWS CloudWatch, Amazon SNS is a transport layer rather than a fixed alert producer. To keep alert creation and resolution predictable, Rootly expects a versioned JSON schema inside the SNS Message field. This schema defines the alert status, summary, external identifier, and any optional metadata used for routing, urgency, labels, and enrichment. When Rootly receives an SNS payload with status: "triggered", it creates a new alert. When Rootly receives a payload with status: "resolved" and the same external_id, it resolves the corresponding alert. Alerts created from SNS can be routed to services, escalation policies, or teams, enriched with labels and metadata, customized with alert fields, and sent directly to specific notification targets using Rootly’s specialized webhook endpoint format.
AWS SNS does not define a native alert schema. Rootly requires a versioned payload contract inside the SNS Message body so alerts can be created and resolved consistently.
AWS SNS alert-source support is currently in beta. We recommend validating your payloads, routing rules, urgency configuration, and resolve behavior in a non-production environment before rolling the integration out broadly.

​
How the Integration Works

Amazon SNS publishes messages to a Rootly-managed HTTPS webhook endpoint generated when you create an AWS SNS alert source in Rootly. When Amazon SNS sends a SubscriptionConfirmation request, Rootly automatically attempts to confirm the subscription. After the subscription is confirmed, SNS delivers Notification messages to the Rootly webhook endpoint. For each incoming notification, Rootly reads the SNS envelope and parses the JSON content stored in the Message field. Rootly validates that message against the supported versioned schema and then uses the following fields to determine behavior:
  • version identifies which Rootly payload contract is being used.
  • status determines whether the alert should be triggered or resolved.
  • summary becomes the alert title unless overridden by alert fields.
  • external_id is used to match trigger and resolve events for the same alert.

​
Prerequisites

Before configuring the integration, ensure that you have access to an AWS account with permissions to manage SNS topics and subscriptions. You must also have a Rootly account with access to Alert Sources.

​
Setup Instructions

1

Create an Alert Source in Rootly

Begin by creating an AWS SNS alert source in Rootly. Navigate to Settings → Alert Sources and click Add Alert Source. Select AWS SNS and provide a descriptive name, such as “Production SNS Alerts.”You may optionally configure default alert urgency, owner groups, alert fields, or deduplication settings. Once the alert source is saved, copy the webhook URL provided by Rootly.
https://webhooks.rootly.com/webhooks/incoming/aws_sns_webhooks?secret=YOUR_SECRET_KEY
The webhook secret authenticates incoming requests from Amazon SNS. Treat this value as sensitive and rotate it if it is exposed.
2

Create an SNS Topic

In the AWS SNS Console, create a new topic using the Standard topic type and give it a clear, descriptive name such as rootly-aws-sns-alerts.This SNS topic acts as the delivery mechanism between your alert publisher and Rootly.
3

Subscribe Rootly to the SNS Topic

Open the SNS topic and navigate to the Subscriptions tab. Create a new subscription using the HTTPS protocol and paste the Rootly webhook URL into the endpoint field.AWS sends a subscription confirmation request to the webhook endpoint. Rootly automatically attempts to confirm this request, and the subscription typically transitions to Confirmed within a few seconds.
If the subscription remains in a pending state, verify that the webhook endpoint is reachable and that no network restrictions are blocking AWS SNS traffic.
4

Publish a Test Message

In the AWS SNS Console, open the topic and click Publish message. Paste a valid Rootly SNS schema payload into the message body.For a minimal trigger test, publish the following JSON as the SNS message body:
{
  "version": 1,
  "status": "triggered",
  "summary": "SNS staging validation trigger",
  "description": "trigger test",
  "external_id": "sns-staging-validation-1"
}
Rootly receives this JSON inside the SNS Message field and validates it before creating the alert.
5

Test Resolution

To resolve the alert, publish another SNS message with the same external_id and status: "resolved".
{
  "version": 1,
  "status": "resolved",
  "summary": "SNS staging validation trigger",
  "description": "resolve test",
  "external_id": "sns-staging-validation-1"
}
After the message is received, Rootly resolves the matching unresolved alert.

​
Supported Payload Schema

Rootly currently supports version 1 of the AWS SNS alert payload schema.
If an SNS notification does not follow the supported schema, Rootly responds with an HTTP 200 status and ignores the payload. This prevents Amazon SNS from repeatedly retrying malformed messages under a retry policy. Rootly still records a validation error for debugging, so you can correct the payload and republish it.

​
Required Fields

  • version
  • status
  • summary
  • external_id

​
Supported Status Values

  • triggered
  • resolved

​
Optional Fields

  • noise
  • description
  • service_ids
  • group_ids
  • environment_ids
  • external_url
  • alert_urgency_id
  • labels
  • data
  • started_at
  • ended_at

​
Version 1 Example

{
  "version": 1,
  "noise": null,
  "status": "triggered",
  "summary": "High CPU usage on web-server-01",
  "description": "CPU usage exceeded 95% for 5 minutes",
  "service_ids": ["550e8400-..."],
  "group_ids": ["660e8400-..."],
  "environment_ids": [],
  "external_id": "alert-12345",
  "external_url": "https://acme.com/alerts/1",
  "alert_urgency_id": "880e8400-...",
  "labels": [
    { "key": "region", "value": "us-east-1" }
  ],
  "data": { "metric": "cpu.usage" },
  "started_at": "2026-03-11T10:00:00Z",
  "ended_at": null
}
Use the same external_id for the triggered and resolved messages that represent the same alert. Rootly uses this value to match resolve events to the correct alert.

​
Alert Mapping and Behavior

Rootly maps SNS schema fields to alert attributes as follows:
  • summary becomes the alert title.
  • description becomes the alert description.
  • external_id is used to correlate trigger and resolve events.
  • external_url becomes the source link.
  • labels are attached to the alert as Rootly labels.
  • data is stored as alert payload metadata and can be used in alert fields, urgency rules, and routing conditions.
  • service_ids, group_ids, and environment_ids can associate the alert with existing Rootly resources.
If you configure alert fields for the source, those fields can override the title, description, and source link shown in Rootly.

​
Advanced Configuration

​
Alert Fields

Alert fields allow you to transform the incoming SNS payload into alert fields using Liquid templates. These fields can be used to customize the alert title, description, and source link, as well as create additional custom fields for routing, urgency, filtering, and reporting. Because SNS messages are stored as alert payload data in Rootly, you can inspect a sample alert from the source and use the alert payload viewer to copy Liquid variables and JSONPath selectors for field configuration.

​
Alert Urgency

AWS SNS alerts can be assigned urgency dynamically using Rootly alert urgency rules. Rules may be based on raw payload JSONPath values or on alert field values generated from the SNS message. If no rule matches, Rootly applies the source’s fallback alert urgency.

​
Deduplication and Resolution

Rootly uses external_id to match trigger and resolve events for the same SNS alert. If you want to suppress repeated notifications that represent the same incoming event, you can also configure a unique identifier in the Events tab and enable duplicate alert suppression. This deduplication setting is separate from the required external_id field:
  • external_id matches triggered and resolved events for the same alert.
  • the Events tab unique identifier can suppress repeated create events before additional alerts are created.

​
Notification Targets

In addition to default routing rules, SNS alerts can be sent directly to specific notification targets using a specialized webhook endpoint. 
https://webhooks.rootly.com/webhooks/incoming/aws_sns_webhooks/notify/{notification_target_type}/{notification_target_id}?secret=YOUR_SECRET_KEY
The notification target type must be one of Service, EscalationPolicy, or Group. The notification target ID must be replaced with the UUID of the corresponding resource.

​
Webhook Payload Structure

Amazon SNS delivers a standard SNS envelope to Rootly. The Rootly alert payload is expected inside the Message field as JSON. At delivery time, the full payload sent by SNS resembles the following structure: 
{
  "Type": "Notification",
  "MessageId": "11111111-1111-1111-1111-111111111111",
  "Message": "{\"version\":1,\"status\":\"triggered\",\"summary\":\"SNS staging validation trigger\",\"description\":\"trigger test\",\"external_id\":\"sns-staging-validation-1\"}"
}
When publishing from the SNS Console, you normally provide only the inner JSON object. Amazon SNS wraps it in the outer envelope automatically.

​
Security Considerations

Rootly webhook endpoints require HTTPS and use a secret key to authenticate incoming requests. SNS subscription confirmation requests are automatically handled by Rootly. If IP allowlisting is enabled for your Rootly instance, ensure that AWS SNS traffic is permitted.

​
Troubleshooting

Verify that the SNS subscription is confirmed and that the webhook URL configured in SNS exactly matches the one provided by Rootly. Confirm that the published SNS message contains valid JSON in the Message field and includes the required Rootly schema fields: version, status, summary, and external_id.
Ensure that the resolved SNS message uses status: “resolved” and the same external_id used when the alert was first triggered. If the external_id differs, Rootly will treat the resolution as unrelated to the original alert.
Confirm that the webhook endpoint is reachable over HTTPS and that no firewall rules or IP allowlisting restrictions are blocking AWS SNS traffic. Also verify that the webhook URL is correctly formatted and includes the required secret parameter.
Rootly validates SNS messages against the supported versioned payload schema. Messages that do not conform to the schema are ignored to prevent repeated SNS retries. Start with the minimal valid payload and then add optional fields incrementally.

​
Best Practices

  • Start with the minimal required schema and add optional fields gradually as you validate your integration.
  • Use a stable and descriptive external_id for every alert lifecycle so Rootly can reliably match trigger and resolve events.
  • Store additional contextual metadata under data so it can be reused in alert fields, urgency rules, and routing conditions.
  • Use alert fields and the payload viewer in Rootly to validate Liquid variables and JSONPath selectors before depending on them for routing or urgency.
  • Periodically publish a trigger and resolve test pair to validate that the integration continues to function as expected.
For additional assistance, consult the Rootly documentation or contact Rootly Support. You may also refer to AWS SNS documentation for more information about topic, subscription, and delivery behavior.