When processing event streams, you typically need to route only specific events to downstream targets -- for example, forwarding only events from a particular source or matching a numeric threshold. Event patterns let you define JSON-based filter rules that select events by field values, prefixes, numeric ranges, IP addresses, and other criteria, so only relevant events reach your targets.
An event pattern must have the same structure as the events it filters. Each field in the pattern corresponds to a field in the event, and only events that match all specified fields are routed to the target.
Pattern structure
An event pattern is a JSON object whose fields correspond to the fields of the events you want to match. Fields present in the pattern are evaluated; fields absent from the pattern are ignored (treated as wildcards).
Example: The following pattern matches events where source is acs.oss:
{
"source": ["acs.oss"]
}Field values in a pattern are arrays. An event matches if the field value equals any element in the array (OR logic). When multiple fields are present, all fields must match (AND logic).
Supported pattern types
EventBridge supports the following pattern types for event streams:
| Pattern type | What it does | Syntax example |
|---|---|---|
| Field value matching | Matches events where a field equals a specific value | "source": ["acs.oss"] |
| Prefix matching | Matches events where a field value starts with a specified string | "source": [{"prefix": "acs."}] |
| Suffix matching | Matches events where a field value ends with a specified string | "subject": [{"suffix": ".jpg"}] |
| Exclusion matching | Matches events where a field value does not equal specified values | "state": [{"anything-but": "initializing"}] |
| Numeric matching | Matches events where a numeric field meets a value or range condition | "c-count": [{"numeric": [">", 0, "<=", 5]}] |
| IP address matching | Matches events where a data field contains a specific IP address or CIDR block | Uses the IP address in a data field as a condition |
| Combined condition matching | Combines multiple filter rules (prefix, suffix, numeric, IP) in a single pattern | Combine any of the above types in one rule |
| Array matching | Matches events where an array field contains specified elements | Matches if the array intersection is non-empty |
| Null or empty string matching | Matches events where a field value is null or an empty string | "eventVersion": [""] |
| Existence matching | Matches events based on whether a field in data exists | "state": [{"exists": false}] |
For complete syntax and usage examples of each pattern type, see Event patterns.
Pattern matching logic
When you define an event pattern, keep the following rules in mind:
AND logic between fields: All fields specified in the pattern must match for an event to pass the filter.
OR logic within a field: If a field value is an array with multiple elements, the event matches if the field equals any one of those elements.
Nested fields: To match nested event fields (such as fields inside
data), nest the pattern fields accordingly. The pattern structure must mirror the event structure at every level.