> ## Documentation Index
> Fetch the complete documentation index at: https://getconvoy.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](../product-manual/organizations-and-projects#incoming-project)
and [outgoing project](../product-manual/organizations-and-projects#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:
```json Filter across scopes theme={null}
{
"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.
```json Simple object match filter theme={null}
{
"event_type": "created"
}
```
#### Nested object match
This filter is used to validate nested webhook payloads.
```json Nesting object match filter theme={null}
{
"event": {
"type": "created"
}
}
```
#### Array contains match
```json Array contains match theme={null}
{
"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.
```json $neq filter theme={null}
{
"event": {
"$neq": "created"
}
}
```
#### Compound filters
These filters are used to match multiple conditions defined in the schema.
```json $or filter theme={null}
{
"$or": [
{
"cities": "london"
},
{
"type": "weekly"
}
]
}
```
```json $and filter theme={null}
{
"$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.
```json $in filter theme={null}
{
"operation": {
"$in": ["created", "deleted"]
}
}
```
```json $nin filter theme={null}
{
"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`
```json Numeric filters theme={null}
{
"age": {
"$gt": 1
}
}
```
#### Array positional filters (currently in beta)
These filters match events with payloads that are array either in the root or nested.
```json Array positional filters theme={null}
{
"$.venues.$.lagos": "lekki"
}
```
#### Regex filters
These filters match events with payloads that match the supplied regex.
```json Regex filters theme={null}
{
"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 |