Monitoring events in AWS Health with Amazon EventBridge

You can use Amazon EventBridge to detect and react to AWS Health events. Then, based on rules that you create, EventBridge invokes one or more target actions when an event matches the values that you specify in a rule. Depending on the type of event, you can capture event information, initiate additional events, send notifications, take corrective action, or perform other actions. For example, you can use AWS Health to receive email notifications if you have AWS resources in your AWS account that are scheduled for updates, such as Amazon Elastic Compute Cloud (Amazon EC2) instances.

Notes

• AWS Health delivers events on a best effort basis. Events aren't always guaranteed to be delivered to EventBridge.

• Any EventBridge rules which you create can only receive notifications for your AWS account. To receive organizational events for other accounts within your AWS Organizations, please see Aggregating AWS Health events using organizational view and delegated administrator access.

You can choose between multiple target types for EventBridge as part of your AWS Health workflow, including:

• AWS Lambda functions

• Amazon Kinesis Data Streams

• Amazon Simple Queue Service (Amazon SQS) queues

• Built-in targets (such as CloudWatch alarm actions)

• Amazon Simple Notification Service (Amazon SNS) topics

For example, you can use a Lambda function to pass a notification to a Slack channel when an AWS Health event occurs. Or, you can use Lambda and EventBridge to send custom text or SMS notifications with Amazon SNS when an AWS Health event occurs.

For samples of automation and customized alerts that you can create in response to AWS Health events, see the AWS Health Tools in GitHub.

Topics

• Creating EventBridge rules for AWS Region coverage
• Monitoring account-specific and public events for AWS Health
• Installing a service-linked role to use AWS Incident Detection and Response
• AWS Health Events Amazon EventBridge Schema
• Pagination of AWS Health events on EventBridge
• Aggregating AWS Health events using organizational view and delegated administrator access
• Integrating AWS Health event monitoring and notifications with JIRA and ServiceNow
• Configuring an EventBridge rule to send notifications about events in AWS Health
• Configuring AWS Chatbot to send notifications about events in AWS Health
• Running operations on EC2 instances automatically in response to events in AWS Health

Creating EventBridge rules for AWS Region coverage

You must create an EventBridge rule for each Region that you want to receive AWS Health events for. If you don’t create a rule, you won’t receive events. For example, to receive events from the US West (Oregon) Region, you must create a rule for this Region.

Setting up an additional rule in a backup Region adds an extra layer of resilience to your workflows, should your primary rule be affected by an ongoing event. Public events for AWS Health are sent simultaneously to both the impacted Region and to a backup Region. See About public events for AWS Health for more information. For all Regions in the standard AWS partition, you can setup a rule in US West (Oregon) as a backup to continue receiving events even if your primary Region is affected by an ongoing issue. The backup Region for the US West (Oregon) Region is US East (N. Virginia) Region.

For example, if you're monitoring events in the Europe (Frankfurt) Region and that Region is temporarily unavailable, then AWS Health will also deliver that event to the US West (Oregon) Region. Next, your back up EventBridge rule sends the event to the targets that you specified. To create a backup rule, follow the procedure below for Configuring an EventBridge rule to send notifications about events in AWS Health and use the US West (Oregon) Region.

Some AWS Health events are not Region-specific. Events that aren't specific to a Region are called global events. These include events sent for AWS Identity and Access Management (IAM). To receive global events, you must create a rule for the US East (N. Virginia) Region for the primary Region and US West (Oregon) Region as the backup Region.

To receive global events in the AWS GovCloud (US), you must create a rule in the AWS GovCloud (US-West) Region.

Monitoring account-specific and public events for AWS Health

When you create an EventBridge rule to monitor events from AWS Health, the rule delivers both account-specific events and public events:

• Account-specific events affect your account and resources, such as an event that tells you about a required update to an Amazon EC2 instance or other scheduled change events.

• Public events appear on the AWS Health Dashboard – Service health. Public events aren't specific to AWS accounts and provide public information about the Regional availability of a service.

Important

To receive both event types, your rule must use the "source": [ "aws.health"] value. Wildcards, such as "source": [ "aws.health*"] won't match the pattern to monitor for any events.

If you're monitoring public events from an AWS Region, we recommend that you create a back up rule. Public events for AWS Health are sent simultaneously to both the impacted Region and to a backup Region. It's recommended that you de-duplicate AWS Health events using eventARN and communicationId because these remain consistent for AWS Health messages sent to the backup Region.

You can identify if an event is public or account-specific in EventBridge, by using the eventScopeCode parameter. Events can have the PUBLIC or ACCOUNT_SPECIFIC. You can also filter your rule on this parameter.

Example: Public events for Amazon Elastic Compute Cloud

The following event shows an operational issue for Amazon EC2 in the US East (N. Virginia) Region.

{
    "version": "0",
    "id": "fd9d4512-1eb0-50f6-0491-d016ae56aef0",
    "detail-type": "AWS Health Event",
    "source": "aws.health",
    "account": "123456789012",
    "time": "2023-02-15T10:07:10Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "eventArn": "arn:aws:health:us-east-1::event/EC2/AWS_EC2_OPERATIONAL_ISSUE",
        "service": "EC2",
        "eventTypeCode": "AWS_EC2_OPERATIONAL_ISSUE",
        "eventTypeCategory": "issue",
        "eventScopeCode": "PUBLIC",
        "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
        "startTime": "Wed, 15 Feb 2023 22:07:07 GMT",
        "lastUpdatedTime": "Wed, 15 Feb 2023 22:07:07 GMT",
        "statusCode": "open",
        "eventRegion": "us-east-1",
        "eventDescription": [{
            "latestDescription": "We are investigating increased API Error rates and Latencies for Amazon Elastic Compute Cloud in the US-EAST-1 Region.",
            "language": "en_US"
        }],
        "page": "1",
        "totalPages": "1",
        "affectedAccount": "123456789012"

    }
}

Installing a service-linked role to use AWS Incident Detection and Response

If you use AWS Incident Detection and Response for your account, then you must install the AWSServiceRoleForHealth_EventProcessor service-linked role in your account.

This role trusts the event-processor.health.amazonaws.com service principal to assume the role. Attached to this role is the AWSHealth_EventProcessorServiceRolePolicy AWS managed policy. This policy lists the permissions that the role can perform, such as calling other AWS services for you.

This role then creates an Amazon EventBridge managed rule in your account. The rule is named AWSHealthEventProcessor-DO-NOT-DELETE. This rule is the required infrastructure for your account so that EventBridge can deliver alarm state change information from your account to AWS Health.

Related information

To learn more, see the following topics:

• Using service-linked roles for AWS Health

• AWS managed policy: AWSHealth_EventProcessorServiceRolePolicy

AWS Health Events Amazon EventBridge Schema

The following is the schema for AWS Health events. Changes or additions to the previous version of the schema are highlighted as "New". A sample payload is provided after the schema.

AWS Health Event Schema

AWS Health Event Schema
Parameter				Description	Required
version				EventBridge Version, currently "0"	Yes
id				The uniqueEventBridge identifier for the event	Yes
detail-type				Describes the detail type. For AWS Health events this will be &AWS Health Event or AWS Health Abuse Event	Yes
source				The event bus source. For AWS Health events this will be aws.health	Yes
account				The accountId to that the AWS Health event was sent to. Note For organizational view this will be different from the affectedAccount if it's received in the management or delegated administrator account.	Yes
time				Time at which the notification was sent to EventBridge. Format: yyyy-mm-ddThh:mm:ssZ.	Yes
region				Identifies the AWS Region that the notification was delivered to. Note This field doesn't indicate the impacted Region for this AWS Health event. This is provided by "detail.eventRegion".	Yes
resources				Describes the list of affected resources within an account, if there are affected resources. Note This field can be empty if there are no resources referenced.	No
detail				This section contains all the details of the AWS Health event, as listed below.	Yes
	eventArn			Unique identifier for the AWS Health event for the specific Region, includes the Region and event id. Note An eventArn isn't unique to a specific customer account or to a Region.	Yes
	service			The AWS service affected by the AWS Health event. For example, Amazon EC2, Amazon Simple Storage Service, Amazon Redshift, or Amazon Relational Database Service.	Yes
	eventTypeCode			The unique identifier for the event type. For example: AWS_EC2_INSTANCE_NETWORK_MAINTENANCE_SCHEDULED and AWS_EC2_INSTANCE_REBOOT_MAINTENANCE_SCHEDULED. Events that include MAINTENANCE_SCHEDULED are generally pushed out approximately two weeks before the startTime. Note All new planned lifecycle events have the event type AWS_{SERVICE}_PLANNED_LIFECYCLE_EVENT.	Yes
	eventTypeCategory			The category code of the event. The possible values are issue, accountNotification, investigation, and scheduledChange.	Yes
	eventScopeCode			Indicates if the AWS Health event is account-specific or public. Possible values are ACCOUNT_SPECIFIC or PUBLIC.	Yes
	communicationId (New)			A unique identifier for this communication for the AWS Health event. Messages with the same communicationId are possible backup messages or pages of a single AWS Health event. This identifier can be used with the accountId to help de-duplicate messages. Note With the pagination feature release, communicationId includes the page number to keep the communicationId unique across pages, for example, 12345678910-1. For more information, see Pagination of AWS Health events on EventBridge.	Yes
	startTime			The start time of the AWS Health event in the format: DoW, DD, MMM, YYYY, HH:MM:SS TZ. Note The start time can be in the future for scheduled events.	Yes
	endTime			The end time of the AWS Health event in the format: DoW, DD MMM YYYY HH:MM:SS TZ. Note endTime may not be provided for events that are set in the future.	No
	lastUpdatedTime			The last update time for the AWS Health event in the format: DoW, DD MMM YYYY HH:MM:SS TZ.	Yes
	statusCode			Status of the AWS Health event. The possible values are open, closed, or upcoming.	Yes
	eventRegion			The impacted Region described by this AWS Health event.	Yes
	eventDescription			A section that describes the AWS Health event. This includes fields for language and text to describe the event.	Yes
		language		Language used in the AWS Health event. This is typically determined by the Region that the event is published to. For the us-east-1 Region, this is typically "en_US".	Yes
		latestDescription		Describes the AWS Health event as it is rendered from the AWS Health API and typically appears on the the AWS Health dashboard. Note For public events, this contains only the latest update and not the entire history of the event.	Yes
	eventMetadata			Additional event metadata that can be provided for the AWS Health event.	No
		<metadata key 1>		metadata key, value strings "keystring1": "keyvalue1" Note The key-value pairs for event metadata are determined by the service that sent the AWS Health event.	No
	affectedEntities			An array that describes the resource value and status of affected resources within this AWS Health event.	No
		entityValue		The resource/entity ID	No
		lastUpdatedtime (New)		The time when this resource/entity status was last updated in the format:DoW, DD MMM YYYY HH:MM:SS TZ	No
		status (new)		The status of the affected resource/entity. Possible values include IMPAIRED, UNIMPAIRED, PENDING, RESOLVED, UNKNOWN.	No
	page (New)			The page this message represents. For more information, see Pagination of AWS Health events on EventBridge. Note Pagination occurs only on resources. Other causes for the 256KB size limit breach will cause the communication to fail.	Yes
	totalPages (New)			The total number of pages for this health event. For more information, see Pagination of AWS Health events on EventBridge. Note You can use this to determine if you received all of the pages of a multi-page communication for an account.	Yes
	affectedAccount (New)			This is the accountId of the impacted account. Note This may be different from the "account" field if this health event is sent to an account that is part of an AWS Organizations and this is received in the management or delegated administrator account.	Yes

Public Health Event - Amazon EC2 operational issue

{
    "version": "0",
    "id": "7bf73129-1428-4cd3-a780-95db273d1602",
    "detail-type": "AWS Health Event",
    "source": "aws.health",
    "account": "123456789012",
    "time": "2023-01-27T09:01:22Z",
    "region": "af-south-1",
    "resources": [],
    "detail": {
        "eventArn": "arn:aws:health:af-south-1::event/EC2/AWS_EC2_OPERATIONAL_ISSUE/AWS_EC2_OPERATIONAL_ISSUE_7f35c8ae-af1f-54e6-a526-d0179ed6d68f",
        "service": "EC2",
        "eventTypeCode": "AWS_EC2_OPERATIONAL_ISSUE",
        "eventTypeCategory": "issue",
        "eventScopeCode": "PUBLIC",
        "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
        "startTime": "Fri, 27 Jan 2023 06:02:51 GMT",
        "endTime": "Fri, 27 Jan 2023 09:01:22 GMT",
        "lastUpdatedTime": "Fri, 27 Jan 2023 09:01:22 GMT",
        "statusCode": "open",
        "eventRegion": "af-south-1",
        "eventDescription": [{
            "language": "en_US",
            "latestDescription": "Current severity level: Operating normally\n\n[RESOLVED] \n\n [03:15 PM PST] We continue see recovery \n\nThe following AWS services were previously impacted but are now operating normally: APPSYNC, BACKUP, EVENTS."
        }],
        "affectedEntities": [],
        "page": "1",
        "totalPages": "1",
        "affectedAccount": "123456789012"
    }
}

Account-specific AWS Health Event - Elastic Load Balancing API Issue

{
    "version": "0",
    "id": "121345678-1234-1234-1234-123456789012",
    "detail-type": "AWS Health Event",
    "source": "aws.health",
    "account": "123456789012",
    "time": "2022-06-10T06:27:57Z",
    "region": "ap-southeast-2",
    "resources": [],
    "detail": {
        "eventArn": "arn:aws:health:ap-southeast-2::event/AWS_ELASTICLOADBALANCING_API_ISSUE_90353408594353980",
        "service": "ELASTICLOADBALANCING",
        "eventTypeCode": "AWS_ELASTICLOADBALANCING_API_ISSUE",
        "eventTypeCategory": "issue",
        "eventScopeCode": "ACCOUNT_SPECIFIC",
        "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
        "startTime": "Fri, 10 Jun 2022 05:01:10 GMT",
        "endTime": "Fri, 10 Jun 2022 05:30:57 GMT",
        "statusCode": "open",
        "eventRegion": "ap-southeast-2",
        "eventDescription": [{
            "language": "en_US",
            "latestDescription": "A description of the event will be provided here"
        }],
        "page": "1",
        "totalPages": "1",
        "affectedAccount": "123456789012"
    }
}

Account-specific AWS Health Event - Amazon EC2 Instance Store Drive Performance Degraded

{
    "version": "0",
    "id": "121345678-1234-1234-1234-123456789012",
    "detail-type": "AWS Health Event",
    "source": "aws.health",
    "account": "123456789012",
    "time": "2022-06-03T06:27:57Z",
    "region": "us-west-2",
    "resources": [
        "i-abcd1111"
    ],
    "detail": {
        "eventArn": "arn:aws:health:us-west-2::event/AWS_EC2_INSTANCE_STORE_DRIVE_PERFORMANCE_DEGRADED_90353408594353980",
        "service": "EC2",
        "eventTypeCode": "AWS_EC2_INSTANCE_STORE_DRIVE_PERFORMANCE_DEGRADED",
        "eventTypeCategory": "issue",
        "eventScopeCode": "ACCOUNT_SPECIFIC",
        "communicationId": "01b0993207d81a09dcd552ebd1e633e36cf1f09a-1",
        "startTime": "Fri, 3 Jun 2022 05:01:10 GMT",
        "endTime": "Fri, 3 Jun 2022 05:30:57 GMT",
        "statusCode": "open",
        "eventRegion": "us-west-2",
        "eventDescription": [{
            "language": "en_US",
            "latestDescription": "A description of the event will be provided here"
        }],
        "affectedEntities": [{
            "entityValue": "i-abcd1111"
        }],
        "page": "1",
        "totalPages": "1",
        "affectedAccount": "123456789012"
    }
}

Pagination of AWS Health events on EventBridge

AWS Health supports pagination of AWS Health events when the list of “resources” or “affectedEntities” causes the size of the message to exceed EventBridge’s 256KB message size limit. Previously, AWS Health didn't communicate the full list of resources with events when it exceeded this limit.

AWS Health now includes all “resources” and “detail.affectedEntities” in the message. If this list of “resources” and “detail.affectedEntities” exceeds 256KB, then AWS Health splits the health event into multiple pages and publish these pages as individual messages in EventBridge. Each page retains the same eventARN and communicationId to help recombine the list of “resources” or “detail.affectedEntities” after all the pages are received.

These additional messages might cause unecessary messages, for example when the EventBridge rule is directed to a human readable interface such as email or chat. Customers with human readable notifications can add a filter for the “detail.page” field to process only the first page, which eliminates the unnecessary messages created from subsequent pages.

Several schema changes are included to support the pagination launch. Each communicationId now includes the hyphenated page number after the communicationId, even when there is only 1 page. There are also two new fields, detail.page and detail.totalPages, which describe the current page number and the total number of pages for the AWS Health event. The information contained in each paginated message is the same except for the list of “detail.affectedEntities” or “resources”. These lists can be reconstructed after all the pages are received. The pages of affected resources and entities are order-agnostic.

Aggregating AWS Health events using organizational view and delegated administrator access

AWS Health supports organizational view and delegated administrator access for AWS Health events published on Amazon EventBridge. When organizational view is turned on in AWS Health, then the management account or a delegated administrator account receives a single feed of AWS Health events from all accounts within your organization in AWS Organizations.

This feature is designed to provide a centralized view to help manage AWS Health events across your organization. Setting up organizational view and an EventBridge rule in the management account doesn't deactivate EventBridge rules for other accounts in your organization.

For more information on enabling organizational view and delegated administrator access on AWS Health, see Aggregating AWS Health Events.

Integrating AWS Health event monitoring and notifications with JIRA and ServiceNow

You can integrate AWS Health events with JIRA and ServiceNow to receive operational and account information, prepare for scheduled changes, and manage Health events using the Service Management Connector (SMC). The SMC Integration with AWS Health can use Health events sent through EventBridge to automatically create, map, and update JIRA tickets and ServiceNow incidents.

You can use organizational view and delegated administrator access to easily manage Health events across the organization within JIRA and ServiceNow, and incorporate AWS Health information directly into your team’s workflow.

For more information on ServiceNow integration using the SMC, see Integrating AWS Health in ServiceNow.

For more information on JIRA Management Cloud integration using the SMC, see AWS Health in JIRA.