Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Filtering events for a subscriber

A filter selects which events a subscriber receives. Attach a FilterConfiguration to the subscriber with one or more filters, each naming a Scope and a Pattern in EventBridge event pattern syntax. For example, a DATA filter with the pattern {"detail":{"amount":[{"numeric":[">",500]}]}} delivers only orders over 500 published with PutEvents. This page describes the filter model; for the pattern operators, see Amazon EventBridge event patterns. Subscriber filters do not support wildcard matching.

How filtering works

Each filter has two parts: a Scope, which is the part of the event the filter examines (DATA, METADATA, or SYSTEM_METADATA; see Event structure: data, metadata, and system metadata), and a Pattern, an event pattern supplied as a JSON string. EventBridge combines the filters in a configuration with AND: an event must match every filter before the subscriber receives it. A subscriber with no FilterConfiguration receives all events.

The three scopes

Example: filter an event published with PutRawEvents

PutRawEvents publishes a payload with a content type. A DATA filter matches the payload directly, and a METADATA filter matches the publisher's metadata map. The following configuration has one filter per scope; the subscriber receives an event only when all three match: the payload's amount is over 500, the metadata key region is EU, and the content type is JSON.

{
    "Filters": [
        { "Scope": "DATA", "Pattern": "{\"amount\":[{\"numeric\":[\">\",500]}]}" },
        { "Scope": "METADATA", "Pattern": "{\"region\":[\"EU\"]}" },
        { "Scope": "SYSTEM_METADATA", "Pattern": "{\"ContentType\":[\"application/json\"]}" }
    ]
}

Example: filter an event published with PutEvents

PutEvents publishes an event in the EventBridge envelope, built from the entry's Source, DetailType, Resources, Time, and Detail. A DATA filter matches this envelope, with your Detail nested under detail. The event's ContentType is application/eventbridge+json, aws:Source and aws:DetailType come from the entry's Source and DetailType, and the envelope also exposes source and detail-type in the DATA scope. The following configuration matches when the amount in the detail is over 500 and the source is com.myapp.storage.

{
    "Filters": [
        { "Scope": "DATA", "Pattern": "{\"detail\":{\"amount\":[{\"numeric\":[\">\",500]}]}}" },
        { "Scope": "SYSTEM_METADATA", "Pattern": "{\"aws:Source\":[\"com.myapp.storage\"]}" }
    ]
}

Example: filter events from an event source

Events that an event source ingests arrive in the EventBridge envelope, with the originating service or partner in aws:Source. To receive only Amazon S3 object-created events for one bucket, match the service in SYSTEM_METADATA and the bucket in DATA. For a partner, match the partner event source name, for example with a prefix on aws.partner/example.com.

{
    "Filters": [
        { "Scope": "SYSTEM_METADATA", "Pattern": "{\"aws:Source\":[\"aws.s3\"]}" },
        { "Scope": "DATA", "Pattern": "{\"detail-type\":[\"Object Created\"],\"detail\":{\"bucket\":{\"name\":[\"amzn-s3-demo-bucket\"]}}}" }
    ]
}

Behavior and limits

A pattern written for the wrong shape does not fail; it matches nothing. Before you rely on a subscriber, publish one event that should match and one that should not, and check both at the target.