How to Filter and Route Events

Filtering is one of Hookdeck Event Gateway's most powerful features for managing the flow of events. It allows you to control precisely which events reach your destinations, serving two primary purposes:

Reducing noise by preventing unwanted or irrelevant events from being processed.
Conditionally routing different types of events from a single source to multiple, specialized destinations.

Whether you're working with webhooks from a third-party service or handling requests to your own async API, filtering provides the flexibility to build robust and efficient workflows. This is all accomplished by applying your Filters to your Connections .

Filtering to remove unwanted events

A common scenario is when a source generates a high volume of events, but a specific downstream service only needs to process a small subset. Instead of overwhelming your destination with irrelevant data, you can apply a filter to the Connection to ensure only the desired events pass through.

For example, you might want to:

Drop noisy "ping" or "health check" events.
Ignore certain event types that are not relevant to a particular service.
Process only events that contain a specific identifier or property.

By setting an inclusion filter, you implicitly exclude all other event types from that Connection, simplifying your endpoint logic and reducing infrastructure load.

For instance, to only allow events where the event_type in the body is order_created, you would apply the following filter rule:

{
  "event_type": {
    "$eq": "order_created"
  }
}

Filtering to conditionally route events

Conditional routing is essential when a single event source needs to trigger workflows across multiple downstream systems. A classic example is an e-commerce platform that emits events for new orders, shipments, and customers. Each of these events needs to be handled by a different service (fulfillment, notifications, CRM).

The architecture for this is straightforward in the Event Gateway:

One Source : Ingests all events from the primary platform (e.g., Shopify, Stripe, or your own API).
Multiple Destinations : One for each target service (e.g., ShipStation, Twilio, HubSpot).
Multiple Connections : A separate Connection is created from the single Source to each Destination. Each Connection has a unique Filter Rule that selects only the events relevant to that specific Destination.

This decouples your routing logic from your application code, allowing you to easily add, remove, or modify routes without deploying new code.

Configuration steps

Setting up filtering and routing follows these simple steps:

Define your Source: Set up the Source that will receive the incoming events or API calls.
Define your Destinations: Set up each of the backend or third-party services where you want to send events.
Create Connections: For each routing condition or filtering rule, create a Connection from your Source to the relevant Destination.
Apply Filter Rules: On each Connection, define the Filter Rule(s) that specify the criteria for an event to be passed through. This can be based on the event's body, headers, or query parameters.
Repeat: Repeat steps 3 and 4 for every unique route you need to create.

Use cases and examples

Routing API events to microservices

In a microservices architecture, a single API gateway might receive various commands that need to be routed to the correct backend service.

Source: An API Source at api.yourcompany.com/ingest.
Destinations: UserService, OrderService, AnalyticsService.
Connections & Filters:
- Connection 1 (to UserService): Filter for user-related events.
```
{ "eventType": { "$eq": "user.created" } }
```
- Connection 2 (to OrderService): Filter for order-related events.
```
{ "eventType": { "$eq": "order.placed" } }
```
- Connection 3 (to AnalyticsService): Filter for events to be used in analytics.
```
{ "eventType": { "$eq": "page.viewed" } }
```

Routing third-party webhooks

Route webhooks from a platform like Shopify to specialized third-party tools.

Source: A single Source for all Shopify webhooks.
Destinations: ShipStation API, Twilio API, HubSpot API.
Connections & Filters:
- Connection 1 (to ShipStation): Filter for new orders using the X-Shopify-Topic header.
```
{ "X-Shopify-Topic": { "$eq": "orders/create" } }
```
- Connection 2 (to Twilio): Filter for shipping updates to send SMS notifications.
```
{ "X-Shopify-Topic": { "$eq": "fulfillments/update" } }
```
- Connection 3 (to HubSpot): Filter for new customer registrations.
```
{ "X-Shopify-Topic": { "$eq": "customers/create" } }
```

Filters Documentation ->

Dive deep into the syntax and operators available for creating powerful filter rules.

Connections Documentation ->

Learn how to create and manage Connections between your Sources and Destinations.

Sources Documentation ->

Explore how to set up Sources to ingest events from webhooks or your own APIs.

Destinations Documentation ->

Find out how to configure Destinations to deliver events to your backend services.

Next -> Overview