> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS SNS

> Receive alerts from Amazon SNS topics in Rootly using a versioned payload schema to create, route, deduplicate, and automatically resolve alerts.

## 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.

<Callout icon="code" color="#DBEAFE">
  AWS SNS does not define a native alert schema. Rootly requires a versioned payload contract inside the SNS <code>Message</code> body so alerts can be created and resolved consistently.
</Callout>

<Callout icon="flask" color="#FEF3C7">
  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.
</Callout>

## 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

<Steps>
  <Step title="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.

    ```txt theme={null}
    https://webhooks.rootly.com/webhooks/incoming/aws_sns_webhooks?secret=YOUR_SECRET_KEY
    ```

    <Callout icon="key" color="#DBEAFE">
      The webhook secret authenticates incoming requests from Amazon SNS. Treat this value as sensitive and rotate it if it is exposed.
    </Callout>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    <Info>
      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.
    </Info>
  </Step>

  <Step title="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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Test Resolution">
    To resolve the alert, publish another SNS message with the same `external_id` and `status: "resolved"`.

    ```json theme={null}
    {
      "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.
  </Step>
</Steps>

## Supported Payload Schema

Rootly currently supports **version 1** of the AWS SNS alert payload schema.

<Callout icon="triangle-exclamation" color="#FEF3C7">
  If an SNS notification does not follow the supported schema, Rootly responds with an HTTP <code>200</code> 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.
</Callout>

### 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

```json theme={null}
{
  "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
}
```

<Callout icon="repeat" color="#DBEAFE">
  Use the same <code>external\_id</code> for the triggered and resolved messages that represent the same alert. Rootly uses this value to match resolve events to the correct alert.
</Callout>

## 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.

```txt theme={null}
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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Why are AWS SNS alerts not being created in Rootly?" icon="circle-exclamation">
    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 <code>Message</code> field and includes the required Rootly schema fields: <code>version</code>, <code>status</code>, <code>summary</code>, and <code>external\_id</code>.
  </Accordion>

  <Accordion title="Why are AWS SNS alerts not being resolved automatically?" icon="rotate">
    Ensure that the resolved SNS message uses <code>status: "resolved"</code> and the same <code>external\_id</code> used when the alert was first triggered. If the <code>external\_id</code> differs, Rootly will treat the resolution as unrelated to the original alert.
  </Accordion>

  <Accordion title="Why is the SNS subscription stuck in Pending confirmation?" icon="signal">
    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.
  </Accordion>

  <Accordion title="Why is Rootly ignoring my SNS message?" icon="circle-exclamation">
    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.
  </Accordion>
</AccordionGroup>

## 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.