Skip to navigation
Events & WebhooksWebhooks

Webhook Filters

Use JSON event filters to apply advanced filtering logic to webhook subscriptions.
View as Markdown

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

{
  "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

{
  "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

{
  "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:

{
  "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

{
  "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)

{
  "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.

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

Match events for leads that had their name or description changed

{
  "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

{
  "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

{
  "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"
            }
          }
        ]
      }
    }
  }
}