Amazon EventBridge event patterns - Amazon EventBridge

Amazon EventBridge event patterns

Event patterns have the same structure as the events they match. Rules use event patterns to select events and send them to targets. An event pattern either matches an event or it doesn't.

Important

In EventBridge, it is possible to create rules that can lead to higher-than-expected charges and throttling. For example, you can inadvertently create a rule that leads to an infinite loop, where a rule is fired recursively without end. Suppose you created a rule to detect that ACLs have changed on an Amazon S3 bucket, and trigger software to change them to the desired state. If the rule is not written carefully, the subsequent change to the ACLs fires the rule again, creating an infinite loop.

For guidance on how to write precise rules and event patterns to minimize such unexpected results, see Best practices when defining Amazon EventBridge rules and Best practices when defining Amazon EventBridge event patterns.

The following video goes over the basics of event patterns:

The following event shows a simple AWS event from Amazon EC2.

{ "version": "0", "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", "detail-type": "EC2 Instance State-change Notification", "source": "aws.ec2", "account": "111122223333", "time": "2017-12-22T18:43:48Z", "region": "us-west-1", "resources": [ "arn:aws:ec2:us-west-1:123456789012:instance/i-1234567890abcdef0" ], "detail": { "instance-id": "i-1234567890abcdef0", "state": "terminated" } }

The following event pattern processes all Amazon EC2 instance-termination events.

{ "source": ["aws.ec2"], "detail-type": ["EC2 Instance State-change Notification"], "detail": { "state": ["terminated"] } }

Creating event patterns

To create an event pattern, you specify the fields of an event that you want the event pattern to match. Only specify the fields that you use for matching. The previous event pattern example only provides values for three fields: the top-level fields "source" and "detail-type", and the "state" field inside the "detail" object field. EventBridge ignores all the other fields in the event when applying the rule.

For an event pattern to match an event, the event must contain all the field names listed in the event pattern. The field names must also appear in the event with the same nesting structure.

When you write event patterns to match events, you can use the TestEventPattern API or the test-event-pattern CLI command to test that your pattern matches the correct events. For more information, see TestEventPattern.

Matching event values

In an event pattern, the value to match is in a JSON array, surrounded by square brackets ("[", "]") so that you can provide multiple values. For example, to match events from Amazon EC2 or AWS Fargate, you could use the following pattern, which matches events where the value for the "source" field is either "aws.ec2" or "aws.fargate".

{ "source": ["aws.ec2", "aws.fargate"] }

Considerations when creating event patterns

Below are some things to consider when constructing your event patterns:

  • EventBridge ignores the fields in the event that aren't included in the event pattern. The effect is that there is a "*": "*" wildcard for fields that don't appear in the event pattern.

  • The values that event patterns match follow JSON rules. You can include strings enclosed in quotation marks ("), numbers, and the keywords true, false, and null.

  • For strings, EventBridge uses exact character-by-character matching without case-folding or any other string normalization.

  • For numbers, EventBridge uses string representation. For example, 300, 300.0, and 3.0e2 are not considered equal.

  • If multiple patterns are specified for the same JSON field, EventBridge only uses the last one.

  • Be aware that when EventBridge compiles event patterns for use, it uses dot (.) as the joining character.

    This means EventBridge will treat the following event patterns as identical:

    ## has no dots in keys { "detail" : { "state": { "status": [ "running" ] } } } ## has dots in keys { "detail" : { "state.status": [ "running" ] } }

    And that both event patterns will match the following two events:

    ## has no dots in keys { "detail" : { "state": { "status": "running" } } } ## has dots in keys { "detail" : { "state.status": "running" } }
    Note

    This describes current EventBridge behavior, and should not be relied on to not change.

  • Event patterns containing duplicate fields are invalid. If a pattern contains duplicate fields, EventBridge only considers the final field value.

    For example, the following event patterns will match the same event:

    ## has duplicate keys { "source": ["aws.s3"], "source": ["aws.sns"], "detail-type": ["AWS API Call via CloudTrail"], "detail": { "eventSource": ["s3.amazonaws.com"], "eventSource": ["sns.amazonaws.com"] } } ## has unique keys { "source": ["aws.sns"], "detail-type": ["AWS API Call via CloudTrail"], "detail": { "eventSource": ["sns.amazonaws.com"] } }

    And EventBridge treats the following two events as identical:

    ## has duplicate keys { "source": ["aws.s3"], "source": ["aws.sns"], "detail-type": ["AWS API Call via CloudTrail"], "detail": [ { "eventSource": ["s3.amazonaws.com"], "eventSource": ["sns.amazonaws.com"] } ] } ## has unique keys { "source": ["aws.sns"], "detail-type": ["AWS API Call via CloudTrail"], "detail": [ { "eventSource": ["sns.amazonaws.com"] } ] }
    Note

    This describes current EventBridge behavior, and should not be relied on to not change.

Comparison operations for use in event patterns

Below a summary of all the comparison operators available in EventBridge.

Comparison operators only work on leaf nodes, with the exception of $or and anything-but.

Comparison Example Rule syntax

And

Location is "New York" and Day is "Monday"

"Location": [ "New York" ], "Day": ["Monday"]

Anything-but State is any value besides "initializing".

"state": [ { "anything-but": "initializing" } ]

Anything-but (begins with)

Region is not in the US.

"Region": [ { "anything-but": {"prefix": "us-" } } ]

Anything-but (ends with)

FileName does not end with a .png extension.

"FileName": [ { "anything-but": { "suffix": ".png" } } ]

Anything-but (ignore case)

State is any value besides "initializing" or any other casing variation, such as "INITIALIZING".

"state": : [{ "anything-but": { "equals-ignore-case": "initializing" }}]}

Begins with

Region is in the US.

"Region": [ {"prefix": "us-" } ]

Begins with (ignore case)

Service name starts with the letters "eventb", regardless of case.

{"service" : [{ "prefix": { "equals-ignore-case": "eventb" }}]}

Empty

LastName is empty.

"LastName": [""]

Equals

Name is "Alice"

"Name": [ "Alice" ]

Equals (ignore case)

Name is "Alice"

"Name": [ { "equals-ignore-case": "alice" } ]

Ends with

FileName ends with a .png extension

"FileName": [ { "suffix": ".png" } ]

Ends with (ignore case)

Service name ends with the letters "tbridge", or any other casing variation, such as "TBRIDGE".

{"service" : [{ "suffix": { "equals-ignore-case": "tBridge" }}]}

Exists

ProductName exists

"ProductName": [ { "exists": true } ]

Does not exist

ProductName does not exist

"ProductName": [ { "exists": false } ]

Not

Weather is anything but "Raining"

"Weather": [ { "anything-but": [ "Raining" ] } ]

Null

UserID is null

"UserID": [ null ]

Numeric (equals)

Price is 100

"Price": [ { "numeric": [ "=", 100 ] } ]

Numeric (range)

Price is more than 10, and less than or equal to 20

"Price": [ { "numeric": [ ">", 10, "<=", 20 ] } ]

Or

PaymentType is "Credit" or "Debit"

"PaymentType": [ "Credit", "Debit"]

Or (multiple fields)

Location is "New York", or Day is "Monday".

"$or": [ { "Location": [ "New York" ] }, { "Day": [ "Monday" ] } ]

Wildcard

Any file with a .png extension, located within the folder "dir"

"FileName": [ { "wildcard": "dir/*.png" } ]

Example events and event patterns

You can use all of the JSON data types and values to match events. The following examples show events and the event patterns that match them.

Field matching

You can match on the value of a field. Consider the following Amazon EC2 Auto Scaling event.

{ "version": "0", "id": "3e3c153a-8339-4e30-8c35-687ebef853fe", "detail-type": "EC2 Instance Launch Successful", "source": "aws.autoscaling", "account": "123456789012", "time": "2015-11-11T21:31:47Z", "region": "us-east-1", "resources": [], "detail": { "eventVersion": "", "responseElements": null } }

For the preceding event, you can use the "responseElements" field to match.

{ "source": ["aws.autoscaling"], "detail-type": ["EC2 Instance Launch Successful"], "detail": { "responseElements": [null] } }

Value matching

Consider the following Amazon Macie event, which is truncated.

{ "version": "0", "id": "0948ba87-d3b8-c6d4-f2da-732a1example", "detail-type": "Macie Finding", "source": "aws.macie", "account": "123456789012", "time": "2021-04-29T23:12:15Z", "region":"us-east-1", "resources": [ ], "detail": { "schemaVersion": "1.0", "id": "64b917aa-3843-014c-91d8-937ffexample", "accountId": "123456789012", "partition": "aws", "region": "us-east-1", "type": "Policy:IAMUser/S3BucketEncryptionDisabled", "title": "Encryption is disabled for the S3 bucket", "description": "Encryption is disabled for the Amazon S3 bucket. The data in the bucket isn’t encrypted using server-side encryption.", "severity": { "score": 1, "description": "Low" }, "createdAt": "2021-04-29T15:46:02Z", "updatedAt": "2021-04-29T23:12:15Z", "count": 2, . . .

The following event pattern matches any event that has a severity score of 1 and a count of 2.

{ "source": ["aws.macie"], "detail-type": ["Macie Finding"], "detail": { "severity": { "score": [1] }, "count":[2] } }