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.
subscription filter
The filters are configured in the Filter Schema editor and the event payload in the Event Payload editor to validate the schema.
Subscription filter

​
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"
}
subscription filter modal

​
Nested object match

This filter is used to validate nested webhook payloads.
Nesting object match filter
{
	"event": {
		"type": "created"
	}
}
subscription filter modal

​
Array contains match

Array contains match
{
	"dish": {
		"ingredients": "rice"
	}
}
subscription filter modal

​
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"
	}
}
$neq subscription filter

​
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"
				}
			]
		}
	]
}
$and filter

​
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"]
	}
}
$in filter

​
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"
}
Array positional $. filter

​
Regex filters

These filters match events with payloads that match the supplied regex.
Regex filters
{
	"event_type": {
		"$regex": "^es_[a-zA-Z]+$"
	}
}
Regex filter

​
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:
OperatorSupported TypeDescription
noneallMatch all
$.arrayMatch an array value
$gtenumberGreater than or equal to
$gtnumberGreater than
$ltnumberLess than
$ltenumberLess than or equal to
$eqnumber, object, string, boolEqual
$neqnumber, object, string, boolNot Equal
$inarraychecks if an array contains a value
$ninarraychecks if an array does not contain a value
$orarray of conditionsmatches an array of conditions
$andarray of conditionsmatches an array of conditions
$existarraychecks if a key exists
$regexstringchecks if the regex matches