Filters

Filtering is used to decide what events an endpoint will receive based on the webhook event payload. The filter is an enriched JSON syntax for both simple and complex filters (such as special logical and numeric operators $or, $gte, $eq).

Use cases

Filters can be configured on subscriptions in both incoming projects and outgoing project.

The filters are configured in the Filter Schema editor and the event payload in the Event Payload editor to validate the schema.

Filter scopes

A subscription filter can match against four scopes of the incoming request: body, headers, query, and path. Body and header matching have been supported for a while; query and path matching are the newer additions, so you can route on the query string and URL path of an inbound request, not just its payload and headers. Each scope is a top-level key in the filter configuration, and the operators documented below apply within each scope independently:

Filter across scopes

{
	"body": {
		"event_type": "order.created"
	},
	"headers": {
		"x-source": "billing"
	},
	"query": {
		"region": "eu"
	},
	"path": {
		"path": "/v2/orders"
	}
}

headers and query expose each header name or query parameter as its own key, so you match them directly (for example region above). path exposes the full request URL path under a single path key, so you match against that whole path string (for example /v2/orders) rather than individual segments. The examples in the rest of this page target the body scope, which is the most common, but the same syntax works inside any scope. Advanced filtering beyond simple event-type matching is a Premium capability.

Simple filters

Simple filters directly match keys to values, and they can be nested. They can also match items in an array.

Direct object match

This filter is used to validate simple JSON webhook payloads.

Simple object match filter

{
	"event_type": "created"
}

Nested object match

This filter is used to validate nested webhook payloads.

Nesting object match filter

{
	"event": {
		"type": "created"
	}
}

Array contains match

{
	"dish": {
		"ingredients": "rice"
	}
}

Complex filters

Complex filters contain more logic such as logical operators and special operators. Complex filters are employed to filter events using one or more conditions, e.g., $or logical operator filter.

Equality filters

This filter matches event which directly does not match the event type in the webhook payload.

$neq filter

{
	"event": {
		"$neq": "created"
	}
}

Compound filters

These filters are used to match multiple conditions defined in the schema.

$or filter

{
	"$or": [
		{
			"cities": "london"
		},
		{
			"type": "weekly"
		}
	]
}

$and filter

{
	"$and": [
		{
			"age": {
				"$gte": 10
			}
		},
		{
			"$or": [
				{
					"type": "weekly"
				},
				{
					"cities": "lagos"
				}
			]
		}
	]
}

Array Contains filters

This filter is used to match keys where the value can be a range of values. It can be used in place of $or if you are comparing on the same field. The opposite of this operator $nin can be used to match keys where the value is not in a range of values.

$in filter

{
	"operation": {
		"$in": ["created", "deleted"]
	}
}

$nin filter

{
	"operation": {
		"$nin": ["updated", "truncated"]
	}
}

Numeric filters

These filters match events based on numeric operators. For example, the filter below will match all events where the age is greater than 1. The operators supported are $gt, $gte, $lt, $lte

Numeric filters

{
	"age": {
		"$gt": 1
	}
}

Array positional filters (currently in beta)

These filters match events with payloads that are array either in the root or nested.

Array positional filters

{
	"$.venues.$.lagos": "lekki"
}

Regex filters

These filters match events with payloads that match the supplied regex.

Regex filters

{
	"event_type": {
		"$regex": "^es_[a-zA-Z]+$"
	}
}

Caveats

Convoy only supports filters with arrays nested up to three levels i.e. $.a.$.b.$.c.$.e will throw an error
Array positional filters are in beta and have time complexity of O(n^3)

Supported Filters

Here’s a full list of the supported filters:

Operator	Supported Type	Description
none	all	Match all
$.	array	Match an array value
$gte	number	Greater than or equal to
$gt	number	Greater than
$lt	number	Less than
$lte	number	Less than or equal to
$eq	number, object, string, bool	Equal
$neq	number, object, string, bool	Not Equal
$in	array	checks if an array contains a value
$nin	array	checks if an array does not contain a value
$or	array of conditions	matches an array of conditions
$and	array of conditions	matches an array of conditions
$exist	array	checks if a key exists
$regex	string	checks if the regex matches

​Use cases

​Filter scopes

​Simple filters

​Direct object match

​Nested object match

​Array contains match

​Complex filters

​Equality filters

​Compound filters

​Array Contains filters

​Numeric filters

​Array positional filters (currently in beta)

​Regex filters

​Caveats

​Supported Filters

Use cases

Filter scopes

Simple filters

Direct object match

Nested object match

Array contains match

Complex filters

Equality filters

Compound filters

Array Contains filters

Numeric filters

Array positional filters (currently in beta)

Regex filters

Caveats

Supported Filters