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

# Ingest CloudWatch Alarms

> Forward AWS CloudWatch alarms to scaling.cloud via SNS to open and resolve incidents automatically.

This guide walks you through forwarding CloudWatch alarms from AWS into scaling.cloud so that `OK → ALARM` opens an incident and `ALARM → OK` resolves it.

For an overview of the integration, see [AWS CloudWatch](/integrations/aws-cloudwatch). If your alarms are defined in AWS CDK, see [Ingest CloudWatch Alarms with AWS CDK](/guides/ingest-cloudwatch-alarms-cdk) instead — the OK transition needs explicit wiring there.

<Frame caption="An AWS integration mapped to a scaling.cloud component">
  <img src="https://mintcdn.com/scalingcloud/5-FlXcH6ySIwHzG0/images/placeholder.svg?fit=max&auto=format&n=5-FlXcH6ySIwHzG0&q=85&s=18ab9c45531fe92b117df1f9652cb357" alt="AWS integration mapping" width="1200" height="675" data-path="images/placeholder.svg" />
</Frame>

## Prerequisites

* A scaling.cloud [component](/concepts/components) representing the AWS service you want to monitor (e.g., **Payments API**).
* Access to the AWS account that hosts the CloudWatch alarms, with permission to create SNS topics and modify alarm actions.
* The **Admin** role in your scaling.cloud organization.

<Steps>
  <Step title="Create an AWS integration in scaling.cloud">
    Go to **Settings → Integrations → AWS** and click **Add integration**.

    * **Name** — a short label (e.g., `Production us-east-1`). Visible in the dashboard only.
    * **Component** — the catalog component this integration's alarms should open incidents on.

    Click **Create**.
  </Step>

  <Step title="Copy the webhook URL">
    scaling.cloud shows you a one-time reveal screen with a unique webhook URL:

    ```
    https://api.scaling.cloud/webhooks/aws/<token>
    ```

    Copy this URL now. It is shown **once** — scaling.cloud stores only a hash. If you lose it, delete the integration and create a new one.
  </Step>

  <Step title="Create an SNS topic in AWS">
    In the AWS console (or via Terraform / CDK), create a new SNS topic:

    * **Type:** Standard (not FIFO).
    * **Region:** the same region as the alarms you want to forward.
    * **Name:** something descriptive, e.g., `scaling-alarms`.

    ```bash theme={null}
    aws sns create-topic --name scaling-alarms --region us-east-1
    ```
  </Step>

  <Step title="Subscribe the webhook URL to the topic">
    Add an HTTPS subscription to the topic, pasting the webhook URL you copied from scaling.cloud. Set `SignatureVersion=2` so SNS signs with RSA-SHA256 — scaling.cloud rejects the legacy RSA-SHA1 (`SignatureVersion=1`) default.

    ```bash theme={null}
    aws sns subscribe \
      --topic-arn arn:aws:sns:us-east-1:123456789012:scaling-alarms \
      --protocol https \
      --notification-endpoint https://api.scaling.cloud/webhooks/aws/<token> \
      --attributes SignatureVersion=2
    ```

    If you subscribed via the console (where `SignatureVersion` isn't exposed) or have an older subscription you can't recreate, update it in place:

    ```bash theme={null}
    aws sns set-subscription-attributes \
      --subscription-arn <subscription-arn> \
      --attribute-name SignatureVersion \
      --attribute-value 2
    ```

    scaling.cloud **auto-confirms** the subscription on first delivery and pins the topic ARN onto the integration. You don't need to click any confirmation link.

    Within a few seconds the subscription should show **Status: Confirmed** in the AWS console.
  </Step>

  <Step title="Route your alarms to the topic">
    On each CloudWatch alarm you want forwarded:

    1. Open the alarm in the CloudWatch console.
    2. Under **Actions**, add the SNS topic as a notification target for **both** the `In alarm` and `OK` state changes.

    Or via Terraform / CDK, set `alarm_actions` and `ok_actions` on the alarm:

    ```hcl theme={null}
    resource "aws_cloudwatch_metric_alarm" "payments_5xx" {
      # ...metric and threshold config...
      alarm_actions = [aws_sns_topic.scaling_alarms.arn]
      ok_actions    = [aws_sns_topic.scaling_alarms.arn]
    }
    ```

    `INSUFFICIENT_DATA` notifications are ignored by scaling.cloud, so you don't need to suppress them.
  </Step>

  <Step title="Verify end-to-end">
    Trigger one of the alarms (or temporarily lower its threshold) to force an `OK → ALARM` transition. Within a few seconds:

    * A new incident appears in scaling.cloud tagged with the mapped component.
    * If the component has an escalation policy attached, the on-call responder is paged.

    Restore the alarm threshold so it returns to `OK`. The open incident should auto-resolve.
  </Step>
</Steps>

## One integration per topic

Each AWS integration maps to one scaling.cloud component. If you want alarms on different services to open incidents on different components, create one SNS topic and one scaling.cloud integration **per component**.

A common pattern:

```
Service A alarms ──► SNS topic A ──► scaling.cloud integration A ──► Component A
Service B alarms ──► SNS topic B ──► scaling.cloud integration B ──► Component B
```

## Cross-region

CloudWatch alarms are region-scoped, but SNS topics can deliver to HTTPS endpoints anywhere. You can route alarms from multiple AWS regions into a single scaling.cloud integration by creating one topic per region and subscribing the same scaling.cloud webhook URL to each.

<Tip>
  If you operate in many AWS regions and want a single dashboard, prefer one integration per **service** (with multiple per-region topics subscribed to the same webhook) over one integration per region. That way every alert for a service lands on the same scaling.cloud component.
</Tip>

## Troubleshooting

| Symptom                                                                      | Where to look                                                                                                                                             |
| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Subscription stays in "Pending confirmation"                                 | The webhook URL is wrong, or DNS isn't routing. Double-check the URL was pasted correctly.                                                                |
| Subscription stuck "Pending" and scaling.cloud logs `weak_signature_version` | Your subscription is on `SignatureVersion=1`. Update it with `aws sns set-subscription-attributes --attribute-name SignatureVersion --attribute-value 2`. |
| Alarm fires in AWS but no incident appears                                   | Confirm the alarm has the SNS topic in its **alarm\_actions**, and the topic ARN matches what's pinned.                                                   |
| Notifications rejected with `topic_arn_mismatch`                             | The integration is pinned to a different topic. Delete the integration and recreate it.                                                                   |
| Same alarm opens multiple incidents                                          | Check that `OK` actions are also routed to the topic — otherwise scaling.cloud can't detect the recovery.                                                 |

## Removing the integration

Delete the integration in **Settings → Integrations → AWS**. Further deliveries to the webhook URL return `404`. Remove the HTTPS subscription from the SNS topic on the AWS side to stop AWS retries.