--- sidebar_label: Filters doc_id: 02003f53-d9f1-4e9d-ae49-11eeff852434 description: >- Control which notifications are sent to channels using MongoDB query syntax filters for targeted alerts. keywords: - filters - notifications - MongoDB query - webhooks - conditional routing --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # Filters Filters let you control **which** notifications are sent to a channel using MongoDB query syntax. Common use cases: - *"Send new deployment notifications to Slack channel #my-org-deployments"* - *"Notify me when scopes are deleted or stopped"* - *"Only send audit events for application changes"* - *"Route parameter changes to a specific team's Slack channel"* :::info Filters apply conditions to the event payload for a given [source](/docs/notifications/sources-and-actions). See the [action reference](/docs/notifications/sources-and-actions#action-reference) for the complete list of filterable actions per source. ::: ## How to create filters The `filters` field supports the use of MongoDB query syntax, allowing you to create complex expressions and conditions. Here's a list of the most common operators: | Operator | Description | | -------- | ----------------------------------------------------------------------------------------- | | `$and` | Joins query clauses with a logical AND. Returns results that match all the conditions. | | `$not` | Inverts the effect of a query predicate. Returns results that do not match the condition. | | `$nor` | Joins clauses with a logical NOR. Returns results that fail to match all conditions. | | `$or` | Joins clauses with a logical OR. Returns results that match any condition. | | `$eq` | Matches values equal to a specified value. | | `$ne` | Matches all values not equal to a specified value. | | `$in` | Matches any of the values specified in an array. | | `$nin` | Matches none of the values specified in an array. | | `$gt` | Matches values greater than a specified value. | | `$gte` | Matches values greater than or equal to a specified value. | | `$lt` | Matches values less than a specified value. | | `$lte` | Matches values less than or equal to a specified value. | | `$regex` | Matches values against a regular expression pattern. | :::info Refer to [MongoDB operators](https://www.mongodb.com/docs/manual/reference/operator/query/) for the full reference. ::: ### Dot notation for nested fields Use dot notation to filter on fields nested inside objects. For example, audit event payloads include an `entity_context` object with account and namespace details. You can target those directly: ```json "filters": { "entity_context.account_id": 1234 } ``` ## Filter examples Here are some examples of how you can set up these criteria, based on the notification source. ### Approval examples #### Set one Slack channel for each namespace ```bash "source": ["approval"], ... "filters": { “details.namespace.slug”: “the-namespace-slug-of-my-team” } ``` #### Set one channel for deployment approvals ```bash "source": ["approval"], ... "filters": { "action": "deployment:create" } ``` #### Set one channel for deleted or stopped scopes ```bash "source": ["approval"], ... "filters": { "$or": [{"action": "scope:stop"}, {"action": "scope:delete"}] } ``` #### Set a channel for all approvals but filter out deployment creates ```bash "source": ["approval"], ... "filters": { "action": { "$ne": "deployment:create" } } ``` ### Service examples #### Set a channel for each service specification ```bash "source": ["service"], ... "filters": { "service.specification.slug": "my-service-specification-slug" } ``` #### Set channels for each development and production application Filter notifications for the application you're using to craft and test your services. ```bash "source": ["service"], ... "filters": { "tags.application_id": "111" } ``` Filter notifications for the application used for production. ```bash "source": ["service"], ... "filters": { "tags.application_id": { "$ne": "222" } } ``` ### Audit examples #### Set a channel to audit activity on applications ```bash "source": ["audit"], ... "filters": { "entity": "application" } ``` #### Set a channel for when an application is created successfully ```bash "source": ["audit"], ... "filters": { "entity": "application", "entity_data.status": "active" } ``` #### Set a channel to receive activity for each account ```bash "source": ["audit"], ... "filters": { "entity_context.account_id": 333 } ``` #### Set a channel for failed operations only (4xx/5xx) ```bash "source": ["audit"], ... "filters": { "status": { "$gte": 400 } } ``` #### Set a channel for multiple entity types ```bash "source": ["audit"], ... "filters": { "entity": { "$in": ["namespace", "application", "deployment"] } } ``` #### Set a channel for deletions only ```bash "source": ["audit"], ... "filters": { "method": "DELETE" } ``` #### Set a channel for a specific account, excluding automated operations ```bash "source": ["audit"], ... "filters": { "entity_context.account_id": 333, "user_type": { "$ne": "service_account" } } ``` #### Track application writes and deletes for specific accounts ```bash "source": ["audit"], ... "filters": { "entity": "application", "method": { "$in": ["POST", "DELETE"] }, "entity_context.account_id": { "$in": [11111111, 22222] } } ``` #### Set a channel to match entities by URL pattern ```bash "source": ["audit"], ... "filters": { "url": { "$regex": "^/namespace" } } ``` ### Telemetry examples #### Set a channel for metric data events ```bash "source": ["telemetry"], ... "filters": { "action": "metric:data" } ``` #### Set a channel for a specific scope provider ```bash "source": ["telemetry"], ... "filters": { "arguments.scope_provider": { "$eq": "3f9c2d5e-7b41-4a88-9f6d-2c1e0b7a9e54" } } ``` ### Entity examples #### Set a channel for scope creation hooks ```bash "source": ["entity"], ... "filters": { "entity": "scope", "action": "scope:create" } ``` #### Set a channel for all application lifecycle events ```bash "source": ["entity"], ... "filters": { "entity": "application" } ``` :::tip Entity source notifications power [entity hooks](/docs/entity-hooks/). Use filters to target specific entity types and lifecycle events. ::: ### Parameters examples #### Set a channel for secret reads ```bash "source": ["parameters"], ... "filters": { "action": "parameter:read-secrets" } ``` #### Set a channel for parameter stores and deletes ```bash "source": ["parameters"], ... "filters": { "$or": [ { "action": "parameter:store" }, { "action": "parameter:delete" } ] } ``` ## Combining filters You can combine multiple operators to build complex filter expressions. Here's a real-world example that notifies on all deployment and scope approvals in production namespaces, except for a specific application: ```json "source": ["approval"], ... "filters": { "$and": [ { "$or": [ { "action": "deployment:create" }, { "action": "scope:stop" }, { "action": "scope:delete" } ] }, { "details.namespace.slug": "production" }, { "details.application.slug": { "$ne": "internal-test-app" } } ] } ``` This filter matches events where: - The action is a deployment creation, scope stop, or scope delete, **AND** - The namespace is `production`, **AND** - The application is **not** `internal-test-app`. :::tip Test your filters incrementally. Start with a broad filter (e.g., just the action), verify that notifications arrive, then add conditions one at a time. :::