Skip to main content

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:

OperatorDescription
$andJoins query clauses with a logical AND. Returns results that match all the conditions.
$notInverts the effect of a query predicate. Returns results that do not match the condition.
$norJoins clauses with a logical NOR. Returns results that fail to match all conditions.
$orJoins clauses with a logical OR. Returns results that match any condition.
$eqMatches values equal to a specified value.
$neMatches all values not equal to a specified value.
$inMatches any of the values specified in an array.
$ninMatches none of the values specified in an array.
$gtMatches values greater than a specified value.
$gteMatches values greater than or equal to a specified value.
$ltMatches values less than a specified value.
$lteMatches values less than or equal to a specified value.
$regexMatches 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.