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.
Filters are supported on virtual webhooks and on native webhooks for some integrations. Check the integration's Feature Support tab for which filters apply. Read more about the differences between native and virtual webhooks here: Understanding virtual webhooks
Filter availability varies by integration type and data model. To see which filters are supported for a webhook, open the integration's Feature Support tab in the dashboard. Filter parameters are listed under List Options; the Virtual Webhook Options section shows the options a virtual webhook uses. 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.
Filters an integration doesn't support are accepted and stored, but have no effect on which events you receive. A few integrations require a filter; if one is missing, create returns an error naming the integration and the filter.
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 programmatically 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.
For setting up webhooks end to end, see How to create and configure webhooks. If a webhook stops delivering, see How to troubleshoot unhealthy webhooks.