Event Grid Event Subscriptions and Filtering

An event subscription connects a topic to an event handler. Filtering in event subscriptions is the mechanism that controls which events each handler receives. Precise filtering reduces unnecessary processing, lowers cost, and keeps each handler focused on the events it actually needs.

What Is an Event Subscription?

An event subscription is a resource in Azure that registers an interest in events from a specific topic. It defines the source topic, the filter criteria, and the delivery endpoint. Event Grid evaluates every published event against all active subscriptions on the topic and delivers the event to each subscription whose filter criteria the event satisfies.

Event Subscription – Key Properties

Filter Types in Event Subscriptions

Filter Type 1: Event Type Filter

The event type filter accepts or rejects events based on the eventType field. Multiple event types can be included. If no event types are specified, the subscription receives all event types from the topic.

Example:
  Topic publishes: BlobCreated, BlobDeleted, BlobRenamed

  Subscription A filter: eventType = ["Microsoft.Storage.BlobCreated"]
  --> Only receives BlobCreated events

  Subscription B filter: eventType = ["Microsoft.Storage.BlobDeleted", "Microsoft.Storage.BlobRenamed"]
  --> Receives BlobDeleted and BlobRenamed events

  Subscription C filter: (no filter)
  --> Receives all three event types

Filter Type 2: Subject Filter

The subject filter matches the subject field of an event using a prefix (begins with) or suffix (ends with) match. Subject filters are case-sensitive. Wildcards are not supported in subject filters — only exact prefix or suffix matching is allowed.

Subject Filter – Prefix Match Example

Blob Storage subject format:
/blobServices/default/containers/{containerName}/blobs/{blobName}

Subscription filter: subject begins with
  "/blobServices/default/containers/images"

This subscription receives events ONLY for blobs in the "images" container.
Events for blobs in "documents" or "videos" containers are ignored.

Subject Filter – Suffix Match Example

Subscription filter: subject ends with ".jpg"

This subscription receives events only for files with the .jpg extension.
Events for .pdf, .png, .txt files are ignored.

Combining Prefix and Suffix

Subscription filter:
  subject begins with "/blobServices/default/containers/images"
  AND subject ends with ".jpg"

This subscription receives events ONLY for .jpg files in the "images" container.
All other events are filtered out.

Filter Type 3: Advanced Filters

Advanced filters apply conditions to any field in the event, including nested fields inside the data object. They support multiple operators and can combine multiple conditions. Each subscription can have up to 25 advanced filter conditions.

Advanced Filter – Supported Operators

Advanced Filter – Field Path Syntax

To filter on a nested field inside the data object, use dot notation: data.fieldName. For deeper nesting: data.order.customer.region.

Advanced Filter – Example 1: Filter on File Size

Custom Topic event data:
{
  "id": "evt-001",
  "eventType": "App.FileUploaded",
  "subject": "/uploads/report.pdf",
  "data": {
    "fileName": "report.pdf",
    "fileSizeBytes": 2097152,
    "category": "finance"
  }
}

Subscription advanced filter:
  Key: data.fileSizeBytes
  Operator: NumberGreaterThan
  Value: 1048576

This subscription receives ONLY events where file size exceeds 1 MB (1,048,576 bytes).
Small files are filtered out.

Advanced Filter – Example 2: Filter on Category

Subscription advanced filter:
  Key: data.category
  Operator: StringIn
  Values: ["finance", "legal", "compliance"]

This subscription receives events only for files in the finance, legal,
or compliance category. All other categories are ignored.

Advanced Filter – Example 3: Boolean Field

Custom event data:
{
  "data": {
    "orderId": "ORD-100",
    "isPriority": true,
    "region": "US-EAST"
  }
}

Subscription advanced filter:
  Key: data.isPriority
  Operator: BoolEquals
  Value: true

Only priority orders trigger this subscription.

Combining Multiple Filters

All filter types work together using AND logic. An event must pass all configured filters to be delivered to the subscription.

Subscription Configuration:
  Event Type Filter:    eventType = ["App.FileUploaded"]
  Subject Filter:       subject begins with "/uploads/finance"
  Advanced Filter 1:    data.fileSizeBytes > 1000000
  Advanced Filter 2:    data.status StringIn ["approved", "final"]

Result: Event must satisfy ALL four conditions.
An uploaded file that is:
  - Of type App.FileUploaded
  - Stored under /uploads/finance
  - Larger than 1 MB
  - With status "approved" or "final"
...will be delivered to this subscription.

Creating an Event Subscription in the Azure Portal

1. Navigate to the topic (System Topic, Custom Topic, or Partner Topic)
2. Click + Event Subscription
3. Enter a Name for the subscription
4. Select the Event Schema (must match the topic schema)
5. Under Filter to Event Types, select specific event types or leave blank for all
6. Under Filters tab, configure subject prefix and suffix filters
7. Click Add advanced filter to add field-level conditions
8. Under Endpoint Details, select the endpoint type and provide the URL
9. Optionally set an expiration date and dead-letter location
10. Click Create

Subscription Expiration

Event subscriptions can have an expiration date and time. After expiration, Event Grid stops delivering events to that subscription and deletes it automatically. This is useful for temporary subscriptions such as those created during testing, maintenance windows, or trial periods.

How Event Grid Evaluates Filters – Performance Note

Event Grid evaluates all active subscriptions on every published event. Broad filters increase the number of deliveries, increasing cost and handler load. Precise filters reduce unnecessary deliveries. Well-designed filter rules keep the system efficient.

Summary

Event subscriptions connect topics to handlers, and filters control exactly which events each handler receives. Event Type filters match the event category. Subject filters match path-based naming conventions. Advanced filters apply fine-grained field-level conditions using a wide range of operators. Combining all three filter types in a single subscription gives precise control over event delivery.