Filters

Filters allow you to permit and route events conditionally based on the contents of their Headers, Body, Query, or Path.

Filters in Hookdeck

The two most common uses of filters are:

• Allowing only events with useful information to pass through to a destination.
• Routing events to different destinations based on their contents, as in a fan out approach.

Filters utilize JSON, and support matching on any value (string, number, boolean, null), on nested objects, and on arrays. There is also support for special operators. For a full rundown of supported schema, see filter syntax.

Filters are applied to an event after a transformation by default, if one is defined. However, you can configure the order of transformations and filters in your connection rules. This allows you to run transformations before or after filters, depending on your use case.

Filter limitations

Filters were designed for JSON payloads. To filter non-JSON payloads, you can use a transformation to convert the payload to JSON. The transformation can be configured to run before the filter.

Basic, non-structured filters, such as partial or exact matches on strings, will function with XML payloads.

Filters syntax

Filters utilize JSON, and support matching on any value (string, number, boolean, null), on nested objects, and on arrays.

Simple matches

Single value match

Example:

false

Simple primitive match

Example:

{
  "type": "order/created",
  "order": {
    "id": 123
  }
}

Nested object match

Example:

{
  "product": {
    "title": "A product",
    "inventory": 0
  }
}

Array contains match

Example:

{
  "product": {
    "tags": [
      "gift",
      "something"
    ]
  }
}

Array contains (multiple) match

Example:

{
  "product": {
    "tags": [
      "gift",
      "something",
      "another"
    ]
  }
}

Non-object match

Example:

"/path/test"

Complex matches using operators

Operators allow for more complex matching strategies, beyond simple equivalency tests.

Examples using operators

Example 1 - Filter if property = value (nested)

Condition: Don't allow "subtype" = "message_changed" OR "subtype" = "message_deleted".

Example 2 - Two properties meet criteria with 'or' condition

Condition: Only allow "subtype" = "message_changed" OR "subtype" = "message_deleted" AND "type"="message".

Example 3 - using $not and $or operators

Condition: Allow "event" = "message" and don't allow "team_id" = "team1" OR "team_id" = "team2".

Example 4 - using $not and $endsWith

Condition: Don't allow where "subtype" ends with "message_changed".

Create or add a filter

Filters are applied to a connection, just like any other rule. You can add a filter when creating a new connection or to an existing connection.

Edit a filter

Editing a filter changes the schema that determines an event's delivery eligibility.

Delete a filter

Deleting a filter allows all events, regardless of content, to pass through a connection unimpeded.

Try out a filter

Use the interactive filter tester to experiment with Body, Headers, Path, and Query. Enter test data and a filter schema to see whether events would be allowed through or filtered out.