Note: While this article focuses examples on AWS Health events and delivery via AWS User Notifications, the principles here apply to any events delivered by Amazon EventBridge. Because AWS User Notifications builds on EventBridge and shares the event pattern format, you can use the filters you create here interchangeably with both services.

Your Amazon EventBridge default event bus automatically receives events from the AWS services you use. These include AWS Health events, communicating current or upcoming changes to the availability and performance of your resources on AWS. Using these operational and informational events you can drive notifications, automations and integrations with other systems. For notifications, your goal should be to create the most specific, targeted messages possible. To do that, you first need to know how to filter for specific events so you can route them to the proper receivers.

The Health events delivered to your default bus are in JSON format. Let’s review an AWS Health event to get a sense of the the key/value pairs available. In Figure #:, note the properties such as the resources showing Amazon Resource Names (ARN) of the affected resources ("arn:ec2-1-101002929",...), the service "EC2", the specific event type code "AWS_EC2_INSTANCE_STORE_DRIVE_PERFORMANCE_DEGRADED", the status code "open", the event region "us-west-2", the affected AWS account number and more. These properties are what we’ll use to filter in or filter out messages to our team.

{
  "version": "0",
  "id": "7bf73129-1428-4cd3-a780-95db273d1602",
  "detail-type": "AWS Health Event",
  "source": "aws.health",
  "account": "123456789012",
  "time": "2023-01-27T01:43:21Z",
  "region": "us-west-2",
  "resources": ["arn:ec2-1-101002929", "arn:ec2-1-101002930", "arn:ec2-1-101002931", "arn:ec2-1-101002932"],
  "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": "1234abc01232a4012345678-1",
    "startTime": "Thu, 27 Jan 2023 13:19:03 GMT",
    "lastUpdatedTime": "Thu, 27 Jan 2023 13:44:13 GMT",
    "statusCode": "open",
    "eventRegion": "us-west-2",
    "eventDescription": [{
      "language": "en_US",
      "latestDescription": "A description of the event will be provided here"
    }],
    "affectedEntities": [{
      "entityValue": "arn:ec2-1-101002929",
      "lastUpdatedTime": "Thu, 26 Jan 2023 19:01:55 GMT",
      "status": "IMPAIRED"
    }, {
      "entityValue": "arn:ec2-1-101002930",
      "lastUpdatedTime": "Thu, 26 Jan 2023 19:05:12 GMT",
      "status": "IMPAIRED"
    }, {
      "entityValue": "arn:ec2-1-101002931",
      "lastUpdatedTime": "Thu, 26 Jan 2023 19:07:13 GMT",
      "status": "UNIMPAIRED"
    }, {
      "entityValue": "arn:ec2-1-101002932",
      "lastUpdatedTime": "Thu, 26 Jan 2023 19:10:59 GMT",
      "status": "RESOLVED"
    }],
    "affectedAccount": "123456789012",
    "page": "1",
    "totalPages": "10"
  }
}

Using the Amazon EventBridge Sandbox

To filter your events, you use an event pattern. An event pattern lists the fields and values you want to match against in the source event. If you aren’t familiar with the event pattern syntax, you can use the EventBridge Sandbox to get started. The Sandbox provides sample events, an event pattern builder and the ability to test patterns against the sample events or events you provide to confirm you patterns match as expected.

Step 1: Create a filter (event pattern) in the Amazon EventBridge Sandbox

1. Open the Amazon EventBridge console at https://console.aws.amazon.com/events/.

2. In the navigation pane, choose Developer resources, then select Sandbox.

3. On the Sandbox page find the Sample event section

4. For Sample events choose AWS Health Event

5. In Event pattern, for Event source select AWS services, for AWS service select Health, for Event type select Specific Health events, for Event Type Specification 1 select Specific service(s) and ELASTICLOADBALANCING, for Event Type Specification 2 select Specific event type categories and issue

6. An event pattern following your specification displays. Select Copy and store this for a later step.

Testing and modifying the event pattern

The event pattern you created matches events where: source EQUALS “aws.health” AND detail-type EQUALS “AWS Health Event” AND service EQUALS "ELASTICLOADBALANCING" AND eventTypeCategory EQUALS "issue"

{
  "source": ["aws.health"],
  "detail-type": ["AWS Health Event"],
  "detail": {
    "service": ["ELASTICLOADBALANCING"],
    "eventTypeCategory": ["issue"]
  }
}

Let’s test it against the sample event in the sandbox.

1. Select the Test Pattern button and confirm text below states “Sample event matched the event pattern”

   Your event pattern matches events for ELASTICLOADBALANCING. But you are interested in events for EC2 as well. Let’s modify the event pattern to match EC2 events too.

2. For Sample events where you selected AWS Health Event, choose Sample event 2

3. Note that for Sample event 2, the service is EC2

4. In Event pattern, choose the Test Pattern button again and confirm the “Sample event did not match the event pattern”

5. For Event Pattern, choose Edit pattern

6. For service, add “EC2” making sure you separate the two items with a comma

7. Your event pattern should match as follows:

   {
     "source": ["aws.health"],
     "detail-type": ["AWS Health Event"],
     "detail": {
       "service": ["ELASTICLOADBALANCING", "EC2"],
       "eventTypeCategory": ["issue"]
     }
   }
   

8. Select the Test Pattern button and confirm text below states “Sample event matched the event pattern”

   

Now your event pattern matches issue events for both the ELASTICLOADBALANCING and EC2 services. You can further customize the event pattern using other comparison operators available in EventBridge. For example, matching strings in event description, including or excluding account numbers or selecting only events that contain certain metadata.

Creating filtered notifications using your event pattern

Now that you have an event pattern, let’s use it as an advanced filter in an AWS User Notifications configuration.

1. Open the AWS User Notifications console at https://console.aws.amazon.com/notifications/.

2. In the navigation pane, choose Notification configurations

3. Choose Create notification configuration

4. For Quick setup, choose Health

5. Enter a name for your configuration.

6. For Event rules choose the Regions to monitor for events, for example US East (N. Virginia), US East (Ohio), US West (N. California), and US West (Oregon).

7. Expand Advanced filter - optional

8. Paste the event pattern you created into the text field.

   

9. For Aggregation settings, leave the default Receive within 5 minutes (recommended).

10. For Delivery channels, choose a contact channel from Email, AWS Console Mobile App and Chat channels. For this example I use a preconfigured Slack channel.

    1. If you do not have Chat channels configured, Select Email and enter a recipient email address.

11. Choose Create notification configuration

You now have a notification configuration using an advanced filter. Only when new events match your filter will a notification be sent to your chosen delivery channel(s).

Wrap Up

Now that you created one advanced filter, experiment in the sandbox with creating filters to match more events. By using different filters with their own notification configurations and recipients, you can deliver just the specific information your teams need and help reduce alert fatigue. To learn more about this topic, refer to Concepts for AWS Health, the AWS Health Events schema for Amazon EventBridge and the AWS User Notifications documentation.