ENTERPRISE: Built-in filters are available for Sensu Enterprise users only.

Reference documentation


The handle_when enterprise filter is used to reduce notification “noise”. Users can define a minimum number of event occurrences before notifications will be sent. Users can also specify a reset time, in seconds, to reset where recurrences are counted from, to control when reminder/update notifications are sent. By default, occurrences is set to 1, and reset is 1800 (30 minutes). The handle_when filter is used by all of the enterprise third-party integrations.



The following is an example of how to configure a check to only notify after 2 occurrences and send reminder/update notifications every 20 minutes. Sensu Enterprise integrations and standard event handlers using the handle_when enterprise filter will have events filtered unless these conditions are met.

  "checks": {
    "load_balancer_listeners": {
      "command": "check-haproxy.rb -s /var/run/haproxy.sock -A",
      "subscribers": [
      "interval": 20,
      "handle_when": {
        "occurrences": 2,
        "reset": 1200

The following is an example of how to apply the handle_when enterprise filter to a standard Sensu pipe handler.

NOTE: The default values for occurrences and reset attributes can be overridden by specifying custom values in your check definitions as shown above. Specifying values for handle_when attributes in a handler definition will have no effect.

  "handlers": {
    "custom_mailer": {
      "type": "pipe",
      "command": "custom_mailer.rb",
      "filter": "handle_when"

Filter specification

handle_when attributes

The following attributes are configured within the {"handle_when": {} } configuration scope.

description The number of occurrences that must occur before an event is handled for a check.
required false
type Integer
default 1
"occurrences": 3
description Time in seconds until the occurrence count is considered “reset”, to allow the event to be handled once again.
required false
type Integer
default 1800
"reset": 3600