How to filter webhook events

July 24, 2024

Webhook filters allow you to only receive data about the events you care about. For instance, if you're subscribed to CRM Deal events from ActiveCampaign, you could filter by company_id to receive data only about deals for a specific company.

Please note that filters are only supported for virtual webhooks at this moment, with few exceptions (e.g. Box supports native webhook filtering). Read more about the differences between native and virtual webhooks here: Understanding virtual webhooks

Filter availability varies by integration type and data model. To determine which filters are supported for a particular virtual webhook, refer to the 'List' section on the Feature Support page of the respective integration. Parameters that end in _id or type can be used as filter options when creating a webhook, helping you tailor your subscriptions to your specific needs.

For example, this is the Feature Support list for CRM Deals by ActiveCampaign:

Notice that this data model supports virtual webhooks as specified under ‘Webhook.' Under ‘List Options', the parameter company_id is shown, indicating that it is possible to use this as a filter.

When creating webhooks via the Unified.to web app, you can specify your filter parameters in the webhook creation form:

When creating a webhook programatically via our API, you can include filters in the payload with a string dictionary of values to filter by. For example, in Javascript:

const options = {
  method: 'POST',
  url: 'https://api.unified.to/unified/webhook',
  headers: {
    authorization: 'bearer YOUR_ACCESS_TOKEN'
  },
  data: {
    filters: {
      company_id: '12345',
    },
    // other payload data if needed
  },
};

const results = await axios.request(options);

Review our complete guide on the webhook API here: Create webhook subscriptions.