Event filters

An event filter is a small Liquid template that processes an incoming event, before handing the event off to the run system. If the template renders false, the event will be ignored. This makes event filters a light-weight mechanism for purposefully filtering out events, often for performance reasons.

This is often useful during large data migration operations, for stores that have Mechanic task subscribing to related topics. (For example: if a store has a task subscribing to shopify/customers/update, and the store's team is about to update hundreds of thousands of customers, they may wish to use Mechanic event filters to programmatically ignore all update events generated by the bulk update.)

Event filters should not be confused with Liquid filters.


Event filters are configured in an account's Mechanic settings.

An event filter has two parts:

  • Name – any descriptive string

  • Template – a Liquid template that renders false for events that should be ignored


When an event is received, Mechanic begins by running any event filters that are present on a store's Mechanic account. (Order is not guaranteed.) Mechanic renders each event filter template, providing the event and shop variables. If an event filter's result equals false, Mechanic halts processing of that event entirely. No tasks are run, in this scenario. Otherwise, processing continues normally, and tasks subscribing to the event's topic will run.

An event that wasn't processed will look something like this, in the Mechanic frontend:

This feature is useful if a Mechanic account is experiencing (or will experience) a large volume of events that (a) don't need to be processed at all, (b) would slow down your account if they were processed (learn more about concurrency), and (c) can be programmatically identified.

You can add, update, and remove event filters at any time. Any changes go into effect immediately.

Last updated