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. See the 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 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:

"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

"source": ["approval"],
...
"filters": {
   “details.namespace.slug”: “the-namespace-slug-of-my-team”
}

Set one channel for deployment approvals

"source": ["approval"],
...
"filters": {
   "action": "deployment:create"
}

Set one channel for deleted or stopped scopes

"source": ["approval"],
...
"filters": {
   "$or": [{"action": "scope:stop"}, {"action": "scope:delete"}]
}

Set a channel for all approvals but filter out deployment creates

"source": ["approval"],
...
"filters": {
   "action": { "$ne": "deployment:create" }
}

Service examples

Set a channel for each service specification

"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.

"source": ["service"],
...
"filters": {
   "tags.application_id": "111"
}

Filter notifications for the application used for production.

"source": ["service"],
...
"filters": {
   "tags.application_id": { "$ne": "222" }
}

Audit examples

Set a channel to audit activity on applications

"source": ["audit"],
...
"filters": {
   "entity": "application"
}

Set a channel for when an application is created successfully

"source": ["audit"],
...
"filters": {
   "entity": "application",
   "entity_data.status": "active"
}

Set a channel to receive activity for each account

"source": ["audit"],
...
"filters": {
   "entity_context.account_id": 333
}

Set a channel for failed operations only (4xx/5xx)

"source": ["audit"],
...
"filters": {
   "status": { "$gte": 400 }
}

Set a channel for multiple entity types

"source": ["audit"],
...
"filters": {
   "entity": { "$in": ["namespace", "application", "deployment"] }
}

Set a channel for deletions only

"source": ["audit"],
...
"filters": {
   "method": "DELETE"
}

Set a channel for a specific account, excluding automated operations

"source": ["audit"],
...
"filters": {
   "entity_context.account_id": 333,
   "user_type": { "$ne": "service_account" }
}

Track application writes and deletes for specific accounts

"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

"source": ["audit"],
...
"filters": {
   "url": { "$regex": "^/namespace" }
}

Telemetry examples

Set a channel for metric data events

"source": ["telemetry"],
...
"filters": {
   "action": "metric:data"
}

Set a channel for a specific scope provider

"source": ["telemetry"],
...
"filters": {
   "arguments.scope_provider": {
      "$eq": "3f9c2d5e-7b41-4a88-9f6d-2c1e0b7a9e54"
   }
}

Entity examples

Set a channel for scope creation hooks

"source": ["entity"],
...
"filters": {
   "entity": "scope",
   "action": "scope:create"
}

Set a channel for all application lifecycle events

"source": ["entity"],
...
"filters": {
   "entity": "application"
}

tip

Entity source notifications power entity hooks. Use filters to target specific entity types and lifecycle events.

Parameters examples

Set a channel for secret reads

"source": ["parameters"],
...
"filters": {
   "action": "parameter:read-secrets"
}

Set a channel for parameter stores and deletes

"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:

"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.

How to create filters​

Dot notation for nested fields​

Filter examples​

Approval examples​

Set one Slack channel for each namespace​

Set one channel for deployment approvals​

Set one channel for deleted or stopped scopes​

Set a channel for all approvals but filter out deployment creates​

Service examples​

Set a channel for each service specification​

Set channels for each development and production application​

Audit examples​

Set a channel to audit activity on applications​

Set a channel for when an application is created successfully​

Set a channel to receive activity for each account​

Set a channel for failed operations only (4xx/5xx)​

Set a channel for multiple entity types​

Set a channel for deletions only​

Set a channel for a specific account, excluding automated operations​

Track application writes and deletes for specific accounts​

Set a channel to match entities by URL pattern​

Telemetry examples​

Set a channel for metric data events​

Set a channel for a specific scope provider​

Entity examples​

Set a channel for scope creation hooks​

Set a channel for all application lifecycle events​

Parameters examples​

Set a channel for secret reads​

Set a channel for parameter stores and deletes​

Combining filters​