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

# AWS CloudWatch

> Forward CloudWatch alarms to scaling.cloud via SNS to automatically open and resolve incidents on the affected component.

The AWS CloudWatch integration turns CloudWatch alarms into scaling.cloud incidents. When an alarm transitions to `ALARM`, scaling.cloud opens a new incident on the mapped component. When it returns to `OK`, the matching open incident is resolved.

<Frame caption="An AWS integration connected 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 CloudWatch integration" width="1200" height="675" data-path="images/placeholder.svg" />
</Frame>

## How it works

1. You create an **AWS integration** in scaling.cloud and pick a [component](/concepts/components) it maps to. scaling.cloud issues a unique webhook URL.
2. In AWS, you create an **SNS topic**, subscribe the webhook URL to it, and route your CloudWatch alarms to that topic.
3. scaling.cloud verifies every incoming SNS notification's signature, **pins** the topic ARN on first delivery, and ingests the alarm.
4. `OK → ALARM` opens a new incident on the mapped component. `ALARM → OK` resolves the matching open incident. `INSUFFICIENT_DATA` is ignored.

```
CloudWatch Alarm → SNS Topic → scaling.cloud webhook → Incident created/resolved
```

## State handling

| Alarm transition         | What scaling.cloud does                                      |
| ------------------------ | ------------------------------------------------------------ |
| `OK → ALARM`             | Opens a new incident on the mapped component.                |
| `ALARM → OK`             | Resolves the open incident matched by the alarm ARN.         |
| `ALARM → ALARM`          | No-op (deduplicated by the alarm's resource identifier).     |
| `OK → INSUFFICIENT_DATA` | No-op.                                                       |
| `INSUFFICIENT_DATA → OK` | No-op.                                                       |
| Replays / re-deliveries  | Idempotent — the same SNS message is processed at most once. |

The opened incident flows through the same pipeline as any other incident: it can have an escalation policy attached, page on-call responders, post to Slack, and appear on a published status page.

## Security model

* **HMAC signature verification** — every SNS notification is verified against AWS's published signing certificate. Notifications with invalid signatures are rejected. scaling.cloud requires `SignatureVersion=2` (RSA-SHA256); RSA-SHA1 (the SNS default) is no longer accepted.
* **Topic ARN pinning** — the first valid `SubscriptionConfirmation` pins the topic ARN on the integration. Subsequent notifications with a different `TopicArn` are rejected.
* **Webhook tokens are revealed once** — when you create the integration, the webhook URL is shown one time only. scaling.cloud stores only a SHA-256 hash; if you lose the URL you must delete and recreate the integration.
* **No payload logging** — scaling.cloud does not log raw SNS payloads at info level. Structured logs reference only `orgId` and `integrationId`.

<Warning>
  Keep your webhook URL secret. Anyone with the URL who can publish a valid signed SNS notification can open incidents in your organization. Rotate the integration if you suspect the URL has been exposed.
</Warning>

## Setup

For a step-by-step walkthrough, see [Ingest CloudWatch alarms](/guides/ingest-cloudwatch-alarms). If your alarms are defined in AWS CDK, see [Ingest CloudWatch alarms with AWS CDK](/guides/ingest-cloudwatch-alarms-cdk) for the TypeScript patterns that wire both ALARM and OK transitions.

In short:

<Steps>
  <Step title="Create the integration in scaling.cloud">
    Go to **Settings → Integrations → AWS** and click **Add integration**. Choose a name and the component you want alarms to open incidents on. Copy the webhook URL on the one-time reveal screen.
  </Step>

  <Step title="Create an SNS topic in AWS">
    In the AWS console, create a new SNS topic (Standard, not FIFO) in the region where your alarms live.
  </Step>

  <Step title="Subscribe the webhook URL">
    Add an HTTPS subscription to the topic, pasting the webhook URL you copied from scaling.cloud. Set the subscription's **SignatureVersion** to `2` (RSA-SHA256) — the SNS default of `1` (RSA-SHA1) is no longer accepted. scaling.cloud will auto-confirm the subscription on first delivery.
  </Step>

  <Step title="Route alarms to the topic">
    On each CloudWatch alarm you want forwarded, set the topic as a notification target for `In alarm` and `OK` state changes.
  </Step>
</Steps>

## One integration per topic

Each AWS integration is bound to **one** mapped component. If you want different alarms to open incidents on different components, create one integration (and one SNS topic) per component.

<Tip>
  A common pattern is one SNS topic per service in AWS, with the service's most important alarms routed there, and one matching scaling.cloud integration mapping that topic to the service's component. This keeps the open-incident signal tight and easy to reason about.
</Tip>

## Removing an integration

Deleting an integration in scaling.cloud stops ingestion immediately — any further deliveries to the webhook URL return `404`. To stop AWS from retrying, remove the HTTPS subscription from the SNS topic on the AWS side.