Skip to content

How to integrate AWS Health events with a custom monitoring platform using direct API polling

6 minute read
Content level: Advanced
0

A guide for teams using custom or proprietary monitoring platforms to integrate AWS Health maintenance events without email or push notifications. Covers a lightweight EC2-based polling script (Phase 1) and a PostgreSQL event store with TTL-based tiered alerting (Phase 2). Applicable to RDS, EKS, Fargate, MSK, and any AWS managed service.

Many teams running custom or proprietary monitoring platforms receive AWS Health maintenance events only by email. At scale, email is impractical — the volume is too high to action, and a dedicated monitoring team cannot onboard a push notification channel into an agent-based platform that queries a structured data source on its own cadence.

This post shows how to surface AWS Health events — scheduled upgrades, lifecycle notifications, and service changes across Amazon RDS, Amazon EKS, AWS Fargate, and Amazon MSK — into a custom monitoring tool using a lightweight Python script on an existing EC2 instance. No new infrastructure is required for Phase 1. Phase 2 extends the same approach with a PostgreSQL event store to eliminate false-positive alerts.

Note: The AWS Health API requires Business or Enterprise Support. The script must call the API from us-east-1 — it is a global endpoint, and calls from other regions return empty results.

The scenario

A dedicated monitoring team operates a proprietary platform that polls structured data sources and raises alerts based on configurable thresholds. AWS Health events need to reach this platform, but email and SNS push notifications are not viable — the agent needs a queryable data source it can poll on its own schedule.

The team already runs an EC2 instance for monitoring workloads. Adding a cron-driven Python script to that instance adds negligible overhead and zero additional AWS infrastructure cost.

Why not use Lambda or EventBridge?

The AWS Health API is included with Business and Enterprise Support at no additional charge. Calling it directly from an existing EC2 instance adds no Lambda invocations, no EventBridge rules, and no new infrastructure to manage. For a monitoring team already running an agent on EC2, a cron script is the natural extension — the entire integration lives in one version-controlled file.

Phase 1 — EC2 script with a CloudWatch gauge metric

In Phase 1 the script publishes a 0/1 gauge metric to CloudWatch for each monitored service. The monitoring agent alarms when the metric equals 1 and auto-clears when it returns to 0.

Architecture:

AWS Health API  →  EC2 Instance (cron)  →  Python Script  →  CloudWatch Metric  →  Monitoring Agent  →  Operations Team
                   [polls directly]         [0 = clear / 1 = active]              [alarms on 1]

Attach this IAM policy to the EC2 instance role:

{
  "Effect": "Allow",
  "Action": [
    "health:DescribeEvents",
    "health:DescribeEventDetails",
    "cloudwatch:PutMetricData"
  ],
  "Resource": "*"
}

Create the script at /opt/scripts/health_to_cloudwatch.py:

#!/usr/bin/env python3
import boto3

SERVICES = ["RDS", "EKS", "FARGATE", "MSK"]
NAMESPACE = "Custom/AWSHealth"

def main():
    health = boto3.client("health", region_name="us-east-1")
    cw     = boto3.client("cloudwatch")
    response = health.describe_events(
        filter={"eventStatusCodes": ["open", "upcoming"]}
    )
    active = {e["service"] for e in response.get("events", [])}
    for svc in SERVICES:
        cw.put_metric_data(
            Namespace=NAMESPACE,
            MetricData=[{
                "MetricName": "PendingMaintenance",
                "Dimensions": [{"Name": "Service", "Value": svc}],
                "Value": 1 if svc in active else 0,
                "Unit": "Count"
            }]
        )

if __name__ == "__main__":
    main()

Add a cron entry to run it every 30 minutes or based on the requirement:

*/30 * * * * /usr/bin/python3 /opt/scripts/health_to_cloudwatch.py >> /var/log/health_poll.log 2>&1

Known limitation: CloudWatch custom metrics cannot be deleted once published — by design. If your team proactively completes a maintenance task before AWS closes the Health event, the metric stays non-zero until the next poll cycle, generating false-positive alerts. Phase 2 addresses this.

Phase 2 — EC2 script with a PostgreSQL event store

Phase 2 replaces the CloudWatch metric with a PostgreSQL event store. Each Health event becomes a row with a TTL timestamp. The monitoring agent queries the database directly and raises tiered alerts based on how close the event is to its deadline. Both alert tiers close automatically after 24 hours.

Architecture:

AWS Health API  →  EC2 Instance (cron)  →  Python Script  →  PostgreSQL DB  ←  Monitoring Agent
                   [polls directly]         [INSERT + TTL]                      [queries]
                                                                                      ↓
                                                               ⚠️  WARNING (≤15 days) → Operations Team
                                                               🔴  CRITICAL (≤3 days) → Operations Team
                                                               [both auto-close in 24h]

Why PostgreSQL over CloudWatch?

DecisionRationale
PostgreSQL over CloudWatchNo immutable-metric problem; TTL-based lifecycle
TTL per recordDB self-cleans; mirrors AWS Health event validity window
Agent queries DB directlyFits the custom monitoring tool's pull model natively
Tiered alerting (15d / 3d)Meaningful lead time without alert fatigue
24-hour auto-closePrevents stale alert accumulation

Setting up Phase 2

Install psycopg2 on the EC2:

pip install psycopg2-binary

Create the schema:

CREATE TABLE health_events (
    event_arn    TEXT PRIMARY KEY,
    service      TEXT NOT NULL,
    region       TEXT,
    status       TEXT NOT NULL,
    ttl_date     TIMESTAMP NOT NULL,
    last_updated TIMESTAMP DEFAULT NOW()
);

Create /opt/scripts/health_to_postgres.py:

#!/usr/bin/env python3
import boto3, psycopg2, os
from datetime import datetime, timedelta

DB_CONFIG = {
    "host":     os.environ["DB_HOST"],
    "dbname":   os.environ["DB_NAME"],
    "user":     os.environ["DB_USER"],
    "password": os.environ["DB_PASSWORD"]
}

def main():
    health = boto3.client("health", region_name="us-east-1")
    response = health.describe_events(
        filter={"eventStatusCodes": ["open", "upcoming"]}
    )
    conn = psycopg2.connect(**DB_CONFIG)
    cur  = conn.cursor()
    for ev in response.get("events", []):
        ttl = ev.get("endTime") or datetime.utcnow() + timedelta(days=30)
        cur.execute("""
            INSERT INTO health_events
                (event_arn, service, region, status, ttl_date, last_updated)
            VALUES (%s, %s, %s, %s, %s, NOW())
            ON CONFLICT (event_arn) DO UPDATE
                SET status=EXCLUDED.status,
                    ttl_date=EXCLUDED.ttl_date,
                    last_updated=NOW()
        """, (ev["arn"], ev["service"],
              ev.get("region", "global"), ev["statusCode"], ttl))
    conn.commit()
    cur.close(); conn.close()

if __name__ == "__main__":
    main()

Alert queries for the monitoring agent:

-- WARNING: events expiring within 15 days
SELECT * FROM health_events
WHERE ttl_date <= NOW() + INTERVAL '15 days'
  AND status = 'open';

-- CRITICAL: events expiring within 3 days
SELECT * FROM health_events
WHERE ttl_date <= NOW() + INTERVAL '3 days'
  AND status = 'open';

Choose the right pattern

CriteriaPhase 1 — EC2 + CloudWatchPhase 2 — EC2 + PostgreSQL
InfrastructureExisting EC2 onlyExisting EC2 + PostgreSQL DB
False-positive riskYes (immutable metrics)None (TTL-based)
Tiered alertingNoYes (15d warning / 3d critical)
Auto-closeNoYes (24 hours)
StatusImplementedProposed

Conclusion

These patterns keep the integration simple — a single cron-driven Python script on infrastructure you already run — while giving your monitoring platform a stable, queryable data source. Before your next scheduled maintenance window:

  • Call the AWS Health API from us-east-1, even if your resources are in another region.
  • Start with Phase 1 to validate end-to-end flow, then migrate to Phase 2 when false positives become a problem.
  • Keep both scripts in version control alongside your monitoring configuration.

Further reading

AWS
EXPERT

published 2 months ago157 views