Skip to main content

Filters

By default, an entity hook fires on every matching event for its nrn, entity, action, and dimensions. With filters, you narrow that down further: the hook only fires when the body of the request that triggered the entity operation matches a MongoDB-style expression.

Common cases:

  • "Only run my deployment hook when the deployment switches traffic to 100%."
  • "Only run my scope hook when the scope is being stopped."
  • "Only run my application hook when the application is being imported from an existing repository."

When to use filters​

Filters are useful whenever the same entity:action pair represents multiple sub-flows and your hook only needs to react to some of them. Without filters you'd have to subscribe to everything and discard events on your end. With filters, nullplatform only sends you the relevant ones, saving you traffic, code paths, and the risk of acting on the wrong event.

💡 Note: If your hook should always fire for the configured entity:action, leave filters unset or empty ({}).

What you can filter on​

The expression in filters is evaluated against the body of the request that triggered the entity operation. So the fields available to filter on are exactly the request body fields documented in the API reference for that operation.

For the entities supported by hooks today:

Entityon: create bodyon: update body
applicationCreate an applicationUpdate an application
scopeCreate a scopeUpdate a scope
deploymentCreate a deploymentUpdate a deployment

Any field shown in those request bodies is fair game in the filter expression, including nested fields via dot notation.

tip

For the full operator reference ($eq, $in, $and, $or, $gte, $regex, dot notation for nested fields, and more), see Notification filters. Entity hook filters use the same engine and the same syntax. The only difference is the payload they evaluate against.

Setting filters on a hook​

You set the filter when you create the hook action, or you patch it later.

On create​

np entity-hook action create \
    --body '{
      "nrn": "organization=1:account=2:namespace=3:application=4",
      "entity": "deployment",
      "action": "deployment:update",
      "when": "after",
      "type": "hook",
      "on": "update",
      "filters": {
        "status": "finalized"
      }
    }'

On update​

Sending filters on a PATCH replaces the stored expression. Sending null clears it, returning the hook to "fires for every matching event".

np entity-hook action update \
    --id 550e8400-e29b-41d4-a716-446655440000 \
    --body '{
      "filters": {
        "$or": [
          { "status": "finalized" },
          { "traffic_percentage": { "$gte": 50 } }
        ]
      }
    }'

To clear the filter, send "filters": null.

Examples​

Only on full traffic switch​

Fire a deployment-update hook only when traffic moves to 100%.

"filters": {
  "traffic_percentage": 100
}

Only on a finalized deployment​

"filters": {
  "status": "finalized"
}

Combine conditions with $or​

Fire only when the deployment is finalized or at least half the traffic has switched.

"filters": {
  "$and": [
    { "status": "finalized" },
    { "traffic_percentage": { "$gte": 50 } }
  ]
}

Match against nested fields​

Use dot notation to reach nested properties of the request body.

"filters": {
  "details.environment": "production"
}
Worked example

For a full step-by-step walkthrough, creating the hook on deployment:write, wiring a notification channel, and adding an $or-based fallback for deployments that finalize without ever reaching 100% traffic, see the Notify when a deployment fully shifts traffic tutorial.