DocumentationAPI Reference
Help CenterAPI ChangelogOpenAPI SpecStatus
Documentation
Help CenterAPI ChangelogOpenAPI SpecStatus

Webhook Event Filters

Only have a subset of Events come through

🚧

Enterprise Support

This feature is currently only available for those on the Enterprise plan. Please contact your Account Team if you are interested in enabling and setting up this feature.

1554

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 Event will go through.

Example

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:

{
  "data": {
    "relationships": {
      "inquiry-template": {
        "data": {
          "id": "itmpl_abc123def456"
        }
      }
    }
  }
}

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

{
  "data": {
    "type": "event",
    "id": "evt_Xzh192s6ZKyUVVf3L7Ynz82M",
    "attributes": {
      "name": "inquiry.completed",
      "payload": {
        "data": {
          "type": "inquiry",
          "id": "inq_J95Dw2iV4H9spDDCqCJNHS7b",
          "attributes": {
            "status": "completed",
            "...": "..."
          },
          "relationships": {
            "inquiry-template": {
              "data": {
                "type": "inquiry-template",
                "id": "itmpl_abc123def456"
              }
            },
            "...": "..."
          }
        }
      }
    }
  }
}

Designing an Event Filter

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

{
  "data": {
    "type": "inquiry",
    "id": "inq_XN8jxMoEhUeihzNypSaFKFfo",
    "attributes": {
      "status": "completed",
      "reference-id": null,
      "...": "...",
      "fields": {
        "address-country-code": {
          "type": "string",
          "value": "US"
        },
        "...": "..."
      }
    },
    "relationships": {
      "inquiry-template": {
        "data": {
          "type": "inquiry-template",
          "id": "itmpl_abc123def456"
        }
      },
      "...": "..."
    }
  }
}

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.

{
  "data": {
    "attributes": {
      "fields": {
        "address-country-code": {
          "value": "US"
        }
      }
    }
  }
}

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.

{
  "data": {
    "attributes": {
      "tags": [
        "INBOUND"
      ]
    }
  }
}

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

{
  "data": {
    "attributes": {
      "tags": [
        "INBOUND",
        "CAMPAIGN ABC"
      ]
    }
  }
}

$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:

{
  "data": {
    "relationships": {
      "inquiry-template": {
        "data": {
          "id": {
            "$or": [
              "itmpl_abc123def456",
              "itmpl_ghi789jkl012"
            ]
          }
        }
      }
    }
  }
}

Hash example:

{
  "data": {
    "relationships": {
      "$or": [
        {
          "inquiry-template": {
            "data": {
              "id": "itmpl_abc123def456"
            }
          }
        },
        {
          "template": {
            "data": {
              "id": "tmpl_foo999bar888"
            }
          }
        }
      ]
    }
  }
}

Updated almost 2 years ago

Next steps