Webhook Event Filters

Description

Webhook Event Filters allow developers to be more selective with which Events they receive. If the filter is a strict subset of the payload data for an Event, the Webhook Event will go through. Otherwise, the Webhook Event will change to skipped.

Filter key casing

Two different rules decide which key inflection a key appears in, so you need to check both.

Attribute and relationship names

Attribute and relationship names — reference-id, created-at, inquiry-template — always follow the key inflection configured on the webhook, on every API version.

A webhook’s key inflection is set on its Overview tab in the Dashboard, under Key inflection. It is Kebab-case by default, and is configured per webhook — it does not follow the key inflection on your API keys.

The same filter has to be written differently for each setting:

1
{
2
  "data": {
3
    "attributes": {
4
      "reference-id": "abc123"
5
    },
6
    "relationships": {
7
      "inquiry-template": {
8
        "data": {
9
          "id": "itmpl_abc123def456"
10
        }
11
      }
12
    }
13
  }
14
}

Field names inside fields

Field names inside data.attributes.fields do not always follow the webhook’s key inflection. Which inflection a field name appears in depends on the API version configured on the webhook:

• API version 2025-10-27 and later — field names are never key inflected. They appear exactly as they are configured on the Inquiry Template, Case Template, or Transaction Type, which is normally snake_case (address_country_code).
• API versions before 2025-10-27 — field names on Inquiries, Cases, and Transactions are key inflected, so they follow the webhook’s key inflection (address-country-code on a Kebab-case webhook).
• Account field names are never key inflected, on any API version.

The same field filter is therefore not portable across an API version change:

1
{
2
  "data": {
3
    "attributes": {
4
      "fields": {
5
        "address_country_code": {
6
          "value": "US"
7
        }
8
      }
9
    }
10
  }
11
}

Examples

Let’s say that you only want inquiry.complete events that are related to specific Inquiry Templates.

On the Webhook create/edit modal, you’d put in JSON similar to the following:

1
{
2
  "data": {
3
    "relationships": {
4
      "inquiry-template": {
5
        "data": {
6
          "id": "itmpl_abc123def456"
7
        }
8
      }
9
    }
10
  }
11
}

This would permit an event like the following, ensuring only inquiry.complete payloads associated with the correct template are triggered.

1
{
2
  "data": {
3
    "type": "event",
4
    "id": "evt_Xzh192s6ZKyUVVf3L7Ynz82M",
5
    "attributes": {
6
      "name": "inquiry.completed",
7
      "payload": {
8
        "data": {
9
          "type": "inquiry",
10
          "id": "inq_J95Dw2iV4H9spDDCqCJNHS7b",
11
          "attributes": {
12
            "status": "completed",
13
            "...": "..."
14
          },
15
          "relationships": {
16
            "inquiry-template": {
17
              "data": {
18
                "type": "inquiry-template",
19
                "id": "itmpl_abc123def456"
20
              }
21
            },
22
            "...": "..."
23
          }
24
        }
25
      }
26
    }
27
  }
28
}

Designing an event filter

If you look at the object in the payload of an Event, you might see something like this.

1
{
2
  "data": {
3
    "type": "inquiry",
4
    "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
5
    "attributes": {
6
      "status": "completed",
7
      "reference-id": null,
8
      "...": "...",
9
      "fields": {
10
        "address-country-code": {
11
          "type": "string",
12
          "value": "US"
13
        },
14
        "...": "..."
15
      }
16
    },
17
    "relationships": {
18
      "inquiry-template": {
19
        "data": {
20
          "type": "inquiry-template",
21
          "id": "itmpl_abc123def456"
22
        }
23
      },
24
      "...": "..."
25
    }
26
  }
27
}

Decide on a particular value that you’re interested in. Let’s say it’s that the Inquiry had a country code of US. You’d then delete everything in the JSON object until only the key/value "value": "US" remained and all of the objects that contain it.

You would end up with the following filter for Inquiries with US addresses.

1
{
2
  "data": {
3
    "attributes": {
4
      "fields": {
5
        "address-country-code": {
6
          "value": "US"
7
        }
8
      }
9
    }
10
  }
11
}

Matching against arrays

To match against an array in your payload, make an array with the elements you want to check for.

Matching on Inquiries with a tag named “INBOUND” would look like this.

1
{
2
  "data": {
3
    "attributes": {
4
      "tags": [
5
        "INBOUND"
6
      ]
7
    }
8
  }
9
}

If you wanted to only receive Events with an “INBOUND” and “CAMPAIGN ABC” tags, you’d make the following.

1
{
2
  "data": {
3
    "attributes": {
4
      "tags": [
5
        "INBOUND",
6
        "CAMPAIGN ABC"
7
      ]
8
    }
9
  }
10
}

$or operator

To allow for multiple criteria, use the $or operator. It can be used on a list of values or JSON object literals.

Value example:

1
{
2
  "data": {
3
    "relationships": {
4
      "inquiry-template": {
5
        "data": {
6
          "id": {
7
            "$or": [
8
              "itmpl_abc123def456",
9
              "itmpl_ghi789jkl012"
10
            ]
11
          }
12
        }
13
      }
14
    }
15
  }
16
}

Hash example:

1
{
2
  "data": {
3
    "relationships": {
4
      "$or": [
5
        {
6
          "inquiry-template": {
7
            "data": {
8
              "id": "itmpl_abc123def456"
9
            }
10
          }
11
        },
12
        {
13
          "template": {
14
            "data": {
15
              "id": "tmpl_foo999bar888"
16
            }
17
          }
18
        }
19
      ]
20
    }
21
  }
22
}

$or on array fields

When using $or to match against a field whose value is an array (like tags), the $or must be placed at the parent level, not directly on the array field. Each option should wrap the array field with the value(s) to match.

This will not work — $or directly on an array field:

1
{
2
  "data": {
3
    "attributes": {
4
      "tags": { "$or": ["US 1", "CAN 1"] }
5
    }
6
  }
7
}

Instead, place $or at the parent level with each option wrapping the array:

1
{
2
  "data": {
3
    "attributes": {
4
      "$or": [
5
        { "tags": ["US 1"] },
6
        { "tags": ["CAN 1"] }
7
      ]
8
    }
9
  }
10
}

This also composes with other filters using AND semantics. For example, to match (tag “US 1” OR tag “CAN 1”) AND (one of several templates):

1
{
2
  "data": {
3
    "attributes": {
4
      "$or": [
5
        { "tags": ["US 1"] },
6
        { "tags": ["CAN 1"] }
7
      ]
8
    },
9
    "relationships": {
10
      "inquiry-template": {
11
        "data": {
12
          "id": {
13
            "$or": ["itmpl_aaa", "itmpl_bbb", "itmpl_ccc"]
14
          }
15
        }
16
      }
17
    }
18
  }
19
}