---
title: Webhook Filters
subtitle: >-
  Use JSON event filters to apply advanced filtering logic to webhook
  subscriptions.
---

More advanced event filtering can be achieved by specifying event filters when
creating/modifying a webhook subscription. For a webhook to be fired the event
must match these extra filters as well as the specified `object_type` and
`action` values.

Event filters use JSON to specify filtering conditions on event fields. The
following filter operators can be combined to apply sophisticated filtering
logic.

- **Equals**: `{"type": "equals", "value": "<value>"}` This filter matches only
  if the entire value is the same as provided.
- **Not Equals**: `{"type": "not_equals", "value": "<value>"}` This filter
  matches only if the value does not match what is provided.
- **Is Null**: `{"type": "is_null"}` This filter matches only if the value of
  the specified field is null.
- **Non Null**: `{"type": "non_null"}` This filter matches only if the value of
  the specified field is non-null.
- **Contains**: `{"type": "contains", "value": "<value>"}` This searches for a
  particular value in an array. It can also be used to match a partial string
  for string fields.
- **And**: `{"type": "and", "filters": [<filter1>, <filter2>, ...]}` This
  matches when all provided individual filters match.
- **Or**: `{"type": "or", "filters": [<filter1>, <filter2>, ...]}` This matches
  when one or more provided individual filters match.
- **Not**: `{"type": "not", "filter": <some other filter>}` This matches when
  the provided filter does not match.

The matching operators above can be applied to individual parts of the event
using these two methods of accessing field values:

- **Field Accessor**:
  `{"type": "field_accessor", "field": "<field name>", "filter": <some other filter>}`
  This filter allows you to access a specific field in a JSON document and match
  this field's value against the specified filter.
- **Any value in an array**:
  `{"type": "any_array_value", "filter": <some other filter>}` This searches for
  any matching values inside a JSON list/array.

### Examples

_`user_id` string field of an event equals
`user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA`_

```json
{
  "type": "field_accessor",
  "field": "user_id",
  "filter": {
    "type": "equals",
    "value": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA"
  }
}
```

_Drill into event to match `user_id` of the `data` object to match events
created by user `user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA`_

```json
{
  "type": "field_accessor",
  "field": "data",
  "filter": {
    "type": "field_accessor",
    "field": "user_id",
    "filter": {
      "type": "equals",
      "value": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA"
    }
  }
}
```

_Match events not created by user
`user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA`_

```json
{
  "type": "field_accessor",
  "field": "data",
  "filter": {
    "type": "field_accessor",
    "field": "user_id",
    "filter": {
      "type": "not",
      "filter": {
        "type": "equals",
        "value": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA"
      }
    }
  }
}
```

You can also use `not_equals` as a filter type in this case:

```json
{
  "type": "field_accessor",
  "field": "data",
  "filter": {
    "type": "field_accessor",
    "field": "user_id",
    "filter": {
      "type": "not_equals",
      "value": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA"
    }
  }
}
```

_Match events where the `user_id` field is non-null_

```json
{
  "type": "field_accessor",
  "field": "user_id",
  "filter": {
    "type": "non_null"
  }
}
```

_Match events for leads with string `travel` in the name (e.g. 'Bluth travel
company', case sensitive)_

```json
{
  "type": "field_accessor",
  "field": "data",
  "filter": {
    "type": "field_accessor",
    "field": "name",
    "filter": {
      "type": "contains",
      "value": "travel"
    }
  }
}
```

_Match events for leads that had their `name` changed. This uses a `contains`
filter because `changed_fields` is an array of field names._

```json
{
  "type": "field_accessor",
  "field": "changed_fields",
  "filter": {
    "type": "contains",
    "value": "name"
  }
}
```

_Match events for leads that had their `name` or `description` changed_

```json
{
  "type": "field_accessor",
  "field": "changed_fields",
  "filter": {
    "type": "or",
    "filters": [
      {
        "type": "contains",
        "value": "name"
      },
      {
        "type": "contains",
        "value": "description"
      }
    ]
  }
}
```

_Match events that have two custom fields set to specific values_

```json
{
  "type": "and",
  "filters": [
    {
      "type": "field_accessor",
      "field": "data",
      "filter": {
        "type": "field_accessor",
        "field": "custom.cf_rR9HjgjI4SYy1X1IlMOozK2VkxMgU5NnHquTR8DVxoQ",
        "filter": {
          "type": "equals",
          "value": "product_1234"
        }
      }
    },
    {
      "type": "field_accessor",
      "field": "data",
      "filter": {
        "type": "field_accessor",
        "field": "custom.cf_vwqYhEFwzPyfCErS8uQ77is1wFLvr9BgVi6cTfbFM48",
        "filter": {
          "type": "equals",
          "value": "sub_product_5678"
        }
      }
    }
  ]
}
```

_Use `any_array_value` to match events that have any address in Maryland, USA_

```json
{
  "type": "field_accessor",
  "field": "data",
  "filter": {
    "type": "field_accessor",
    "field": "addresses",
    "filter": {
      "type": "any_array_value",
      "filter": {
        "type": "and",
        "filters": [
          {
            "type": "field_accessor",
            "field": "state",
            "filter": {
              "type": "equals",
              "value": "MD"
            }
          },
          {
            "type": "field_accessor",
            "field": "country",
            "filter": {
              "type": "equals",
              "value": "US"
            }
          }
        ]
      }
    }
  }
}
```