AWS CloudWatch

Navi.sh receives CloudWatch alarm state-change events through Amazon SNS. The SNS topic forwards notifications to the Navi.sh endpoint, and the inner alarm payload is parsed automatically.

POST/v1/events/cloudwatch/{token}

Setup

Your integration URL — including the token — is available in the Navi.sh dashboard → Integrations → CloudWatch.

1. Create an SNS topic (if you don't have one)

aws sns create-topic --name navi-sh-alerts --region us-east-1

2. Subscribe the Navi.sh endpoint

aws sns subscribe \
  --topic-arn arn:aws:sns:us-east-1:<account-id>:navi-sh-alerts \
  --protocol https \
  --notification-endpoint "https://api.navi.sh/v1/events/cloudwatch/<token>"

Navi.sh automatically handles the SubscriptionConfirmation request — no manual confirmation step is needed.

3. Attach the SNS topic to your CloudWatch alarms

In the AWS Console go to CloudWatch → Alarms, open an alarm, and set the SNS topic as the notification action for the In alarm and OK states.

Using the CLI:

aws cloudwatch put-metric-alarm \
  --alarm-name "HighCPUUtilization" \
  --alarm-actions "arn:aws:sns:us-east-1:<account-id>:navi-sh-alerts" \
  --ok-actions "arn:aws:sns:us-east-1:<account-id>:navi-sh-alerts" \
  --metric-name CPUUtilization \
  --namespace AWS/EC2 \
  --statistic Average \
  --period 300 \
  --threshold 80 \
  --comparison-operator GreaterThanThreshold \
  --evaluation-periods 2

TIP

Add the SNS topic to both Alarm actions and OK actions so Navi.sh can auto-resolve incidents when the metric recovers.

Auto-resolve

When CloudWatch transitions an alarm to the OK state, Navi.sh auto-resolves the corresponding incident matched by AlarmName.

POST /v1/events/cloudwatch/{token}

Accepts AWS SNS notifications wrapping CloudWatch alarm state-change events. Configure an SNS subscription pointing to this URL from your CloudWatch alarm.

• SubscriptionConfirmation messages are acknowledged automatically.
• Alarms in state "OK" auto-resolve the corresponding incident.
• Deduplicates by AlarmName.

The token is generated in your navi.sh workspace under Integrations.

Payload schema

Field	Type	Description
Message	string	JSON-encoded CloudWatch alarm payload (CloudWatchAlarmPayload). (example: {"AlarmName":"HighCPU","NewStateValue":"ALARM"})
Subject	string	Human-readable SNS subject. (example: ALARM: HighCPU in US East (N. Virginia))
SubscribeURL	string	Present only for SubscriptionConfirmation messages. (example: https://sns.us-east-1.amazonaws.com/?Action=ConfirmSubscription&Token=abc)
TopicArn	string	ARN of the SNS topic. (example: arn:aws:sns:us-east-1:123456789012:MyTopic)
Type	string (Notification, SubscriptionConfirmation)	SNS message type. SubscriptionConfirmation messages are handled automatically. (example: Notification)

Examples

Alarm State Change

{
  "Message": "{\"AlarmName\":\"HighCPUUtilization\",\"AlarmDescription\":\"CPU \u003e 80%\",\"NewStateValue\":\"ALARM\",\"OldStateValue\":\"OK\",\"NewStateReason\":\"Threshold Crossed\",\"StateChangeTime\":\"2024-01-15T10:30:00Z\",\"Region\":\"us-east-1\",\"AWSAccountId\":\"123456789012\"}",
  "Subject": "ALARM: HighCPU in us-east-1",
  "TopicArn": "arn:aws:sns:us-east-1:123456789012:MyTopic",
  "Type": "Notification"
}

Response codes

• 202 — Accepted — processing is asynchronous
• 400 — Invalid request body (malformed JSON or wrong content type)
• 401 — Invalid service token
• 500 — Unexpected server error