HookFlow

Filtering Webhooks

HookFlow allows you to set up filtering rules to control which webhooks are forwarded to your destinations. This guide explains how to create and manage filter rules to process only the webhooks you need.

Why Filter Webhooks?

Filtering webhooks provides several benefits:

  • Reduced Noise: Only process webhooks relevant to your application
  • Lower Processing Costs: Minimize the number of webhooks that need to be processed
  • Improved Performance: Reduce load on your systems by filtering out unnecessary events
  • Environment Separation: Send different webhooks to development and production environments
  • Event-Based Routing: Direct different types of webhooks to different endpoints

How Filtering Works

Filtering in HookFlow is applied on a per-destination basis. This means:

  • Each destination can have its own set of filter rules
  • A webhook must pass all filter rules to be forwarded to a destination
  • Filtering occurs before transformations are applied
  • All webhooks are still logged, even if they don't pass the filters

Original Webhook Payload

Filter Rules Applied

Passes Filter

Fails Filter

Transform & Deliver

Not Delivered

Filter Conditions

HookFlow supports a variety of filter conditions to match webhook payloads:

Equals

Check if a field exactly matches a specific value.

Example:

event_type equals "payment.succeeded"

Not Equals

Check if a field does not match a specific value.

Example:

environment not equals "test"

Contains

Check if a string field contains a specific substring.

Example:

event_type contains "payment"

Starts With

Check if a string field starts with a specific prefix.

Example:

customer.id starts with "cus_"

Greater Than

Check if a numeric field is greater than a specific value.

Example:

amount greater than 1000

Less Than

Check if a numeric field is less than a specific value.

Example:

created_at less than "2023-01-01"

Exists

Check if a field exists in the payload.

Example:

metadata.campaign_id exists

Matches Regex

Check if a field matches a regular expression pattern.

Example:

email matches regex "^[a-z0-9]+@example\.com$"

Configuring Filter Rules

You can configure filter rules when creating or editing a destination:

  1. Navigate to the source that contains the destination
  2. Click on the destination to expand its settings
  3. Scroll to the "Filter Rules" section
  4. Click "Add Filter Rule" to create a new rule
  5. Configure the rule with the following settings:
    • Field Path: The JSON path to the field you want to filter on
    • Condition: The type of comparison to perform
    • Value: The value to compare against (not required for "exists" condition)
  6. Add additional rules as needed (all rules must pass for the webhook to be forwarded)
  7. Save your changes

Note: All filter rules for a destination must pass for the webhook to be forwarded. If you need OR logic (forward if any rule passes), create separate destinations with the same target URL but different filter rules.

Common Filtering Scenarios

Here are some common filtering scenarios and how to implement them:

Filter by Event Type

Only forward specific types of events to a destination.

Example (Stripe):

Field Path: type
Condition: equals
Value: payment_intent.succeeded

Example (GitHub):

Field Path: event
Condition: equals
Value: push

Filter by Environment

Separate test and production webhooks.

Production Only:

Field Path: livemode
Condition: equals
Value: true

Test Only:

Field Path: livemode
Condition: equals
Value: false

Filter by Amount

Only process transactions above or below a certain amount.

High-Value Transactions:

Field Path: data.object.amount
Condition: greater than
Value: 10000

Filter by Metadata

Use custom metadata to control webhook routing.

Example:

Field Path: data.object.metadata.team
Condition: equals
Value: billing

Advanced Filtering Strategies

Combining Multiple Rules

You can combine multiple filter rules to create more complex conditions. Remember that all rules must pass for the webhook to be forwarded.

Example: High-value production payments

  1. Rule 1: type equals "payment_intent.succeeded"
  2. Rule 2: livemode equals true
  3. Rule 3: data.object.amount greater than 10000

Using OR Logic with Multiple Destinations

Since filter rules within a destination use AND logic (all must pass), you can implement OR logic by creating multiple destinations with the same target URL but different filter rules.

Example: Forward payment or subscription events

  • Destination 1: Same target URL with filter "type contains 'payment'"
  • Destination 2: Same target URL with filter "type contains 'subscription'"

Filtering with Regular Expressions

For more complex pattern matching, use the "matches regex" condition. This is particularly useful for matching email domains, product IDs with specific formats, or other pattern-based filtering.

Example: Only forward webhooks for company email addresses

Field Path: data.object.email
Condition: matches regex
Value: ^[a-zA-Z0-9._%+-]+@(example\.com|example\.org)$

Best Practices

Follow these best practices when configuring webhook filters:

  • Start with broader filters: Begin with more inclusive filters and narrow them down as needed
  • Test thoroughly: Verify filter rules with sample webhooks before deploying
  • Monitor filtered webhooks: Regularly check which webhooks are being filtered out to ensure you're not missing important events
  • Use descriptive names: Give your destinations clear names that indicate their filter criteria
  • Document your filtering strategy: Keep track of which webhooks go where and why

Next Steps

Now that you understand how to filter webhooks, explore these related topics: