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.

Endpoint: POST /api/v1/events/cloudwatch/{token}

---

Setup

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/api/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" \
  # ... other alarm parameters

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.

---

Payload structure

The outer SNS envelope:

Field	Type	Description
Type	string	Notification or SubscriptionConfirmation.
Message	string	JSON-encoded CloudWatchAlarmPayload (see below).
Subject	string	Human-readable subject.
TopicArn	string	ARN of the SNS topic.
SubscribeURL	string	Present only for SubscriptionConfirmation.

The Message JSON (CloudWatch alarm):

Field	Type	Description
AlarmName	string	Alarm name — used as the dedup key.
AlarmDescription	string	Optional description.
NewStateValue	string	ALARM, OK, or INSUFFICIENT_DATA.
OldStateValue	string	Previous state.
NewStateReason	string	Human-readable explanation of the state change.
StateChangeTime	string (RFC3339)	When the state changed.
Region	string	AWS region.
AWSAccountId	string	AWS account ID.
Trigger.MetricName	string	Metric name.
Trigger.Namespace	string	CloudWatch namespace (e.g. AWS/EC2).
Trigger.Dimensions	array	List of {name, value} dimension pairs.

---

Example SNS message

{
  "Type": "Notification",
  "TopicArn": "arn:aws:sns:us-east-1:123456789012:navi-sh-alerts",
  "Subject": "ALARM: HighCPUUtilization in us-east-1",
  "Message": "{\"AlarmName\":\"HighCPUUtilization\",\"AlarmDescription\":\"CPU > 80% for 5 consecutive periods\",\"NewStateValue\":\"ALARM\",\"OldStateValue\":\"OK\",\"NewStateReason\":\"Threshold Crossed: 1 datapoint (85.0) was greater than the threshold (80.0).\",\"StateChangeTime\":\"2024-01-15T10:30:00Z\",\"Region\":\"us-east-1\",\"AWSAccountId\":\"123456789012\",\"Trigger\":{\"MetricName\":\"CPUUtilization\",\"Namespace\":\"AWS/EC2\",\"Unit\":\"Percent\",\"Period\":300,\"Statistic\":\"Average\",\"Dimensions\":[{\"name\":\"InstanceId\",\"value\":\"i-0abc123456789\"}]}}"
}

---

Response

202 Accepted — the alarm payload was queued for processing.