Amazon CloudWatch

What it does

The Amazon CloudWatch adapter accepts inbound webhook events at /api/integrations/cloudwatch, validates them through its custom handler, normalizes provider payloads, and submits lifecycle events to the configured service.

Prerequisites

An OpsKnight service and enabled integration record.
Permission to create or use an Amazon SNS topic and change CloudWatch alarm actions.
The exact SNS topic ARN in the same AWS partition/region used for the alarm action.
A network path from the provider to the OpsKnight web runtime.

Setup and configuration

In Amazon SNS → Topics, create or select a Standard topic dedicated to the intended OpsKnight service/environment. Copy its full topic ARN.
In OpsKnight, open Services → select service → Integrations → Add integration → Amazon CloudWatch.
Enter the exact SNS Topic ARN, save, and copy the generated HTTPS endpoint containing integrationId.
In Amazon SNS → Subscriptions → Create subscription, select that topic, choose HTTPS, paste the OpsKnight endpoint, and create it.
Wait for the subscription to become Confirmed. OpsKnight accepts and follows the confirmation URL only after validating the SNS signature, topic ARN, AWS host, and subscription URL.
In CloudWatch → Alarms, create or edit the alarm. Under notification actions, send the required state changes to the same SNS topic. Configure at least ALARM; configure OK when recovery should resolve the incident. Decide deliberately whether INSUFFICIENT_DATA should page.
Save the alarm and use a controlled threshold/test metric or publish a representative SNS notification to validate the path.

Do not use an email subscription or an arbitrary generic webhook payload. CloudWatch alarm actions publish an alarm message to SNS, and SNS delivers its signed envelope to OpsKnight.

Authentication and request verification

The endpoint requires the integration identifier. Signature verification is none using the cloudwatch verification contract. The exact payload schema is defined by src/app/api/integrations/cloudwatch/route.ts and src/lib/integrations/cloudwatch.ts.

Method: POST
Integration identifier: query parameter
Integration key transports: none; this route uses the authentication contract above
Schema: shared provider schema
Body limit: 1048576 bytes (1 MiB)
Rate limit: 100 requests per 60 seconds, per integration

Event mapping and incident lifecycle

The adapter emits the lifecycle actions found in its current source:

trigger
resolve Correlation contract: adapter EventPayload.dedup_key. Recovery contract: adapter emits resolve for its recovery state.

Recovery and deduplication

This route has no provider delivery-ID fence; incident convergence relies on the adapter deduplication key. Incident convergence still depends on the adapter correlation key. Failed deliveries are recorded for operational inspection without exposing secrets.

Limits and testing

Per-integration rate limiting protects the ingestion path. Send a representative trigger and recovery pair in a non-production service, verify that one incident is created, and confirm that recovery updates that incident rather than creating another.

Verify the connection

After the test alert, confirm all of the following:

One incident appears for the selected OpsKnight service.
The incident source identifies Amazon CloudWatch.
A repeat event updates or correlates according to the adapter identity.
A recovery event resolves the correlated incident.

Error reference

400 — Invalid request or payload validation failed.
401 — Configured authentication or signature validation failed.
403 — Integration is disabled.
404 — Integration record was not found.
413 — Payload exceeds the one MiB body limit.
429 — Per-integration request rate exceeded.
500 — Provider event processing failed.

Troubleshooting

Confirm the integration is enabled, belongs to the intended service, and stores the exact topic ARN.
In SNS, confirm the HTTPS subscription is Confirmed, not PendingConfirmation, and its endpoint contains the correct integration ID.
Inspect Settings → Integrations → Failures for schema, topic-binding, certificate URL, or SNS signature errors.
Check SNS delivery status/logging and CloudWatch alarm action configuration in the same region.
Check for 413 or 429 before retrying rapidly.
Preserve SNS message ID, topic ARN, alarm/state, region, and timestamp when escalating; never expose credentials.

Security

Use HTTPS, rotate exposed keys at both systems, configure signature verification when supported, and restrict provider egress or ingress controls without blocking legitimate retries.