Advanced Filtering

​

Advanced Filtering

Advanced filters allow you to create sophisticated event filtering logic using multiple conditions and logical operators. This enables you to keep your topics generic while precisely controlling which events reach each subscription.

They also unlock dynamic workflows, allowing you to adjust which workflow is used based on data in the event. Which is a very powerful way of working with agents

​

Complex Filter Structure

Advanced filters use a structured approach with multiple filter conditions combined using logical operators:

{
  filters: [
    {
      path: "user.type",
      condition: "equals",
      value: "premium"
    },
    {
      path: "order.total",
      condition: "not_equals",
      value: "0"
    }
  ],
  operator: "and"
}

​

Filter Conditions

​

Available Conditions

​

Logical Operators

​

Real-World Examples

​

E-commerce Order Processing

Only process paid orders from premium customers:

await client.admin.registerPushSubscription(
  "orders",
  "premium-paid-orders",
  "https://api.shop.com/process-premium-order",
  {
    filter: {
      filters: [
        { path: "customer.tier", condition: "equals", value: "premium" },
        { path: "payment.status", condition: "equals", value: "paid" },
        { path: "order.total", condition: "not_equals", value: "0" }
      ],
      operator: "and"
    },
    rate_limit: "50/h",
    deduplication: "10m"
  }
);

​

User Onboarding

Welcome new users but exclude test accounts:

await client.admin.registerPushSubscription(
  "user-events",
  "new-user-welcome",
  "https://api.app.com/welcome-user",
  {
    filter: {
      filters: [
        { path: "event.type", condition: "equals", value: "user_created" },
        { path: "user.email", condition: "not_equals", value: "test@example.com" },
        { path: "user.verified", condition: "equals", value: "true" }
      ],
      operator: "and"
    },
    deduplication: "1h"
  }
);

​

Marketing Campaigns

Target high-value customers for special offers:

await client.admin.registerPushSubscription(
  "customer-activity",
  "vip-offers",
  "https://marketing.app.com/send-vip-offer",
  {
    filter: {
      filters: [
        { path: "customer.lifetime_value", condition: "not_equals", value: "0" },
        { path: "customer.segment", condition: "equals", value: "vip" }
      ],
      operator: "or"
    },
    rate_limit: "10/d",
    deduplication: "24h"
  }
);

​

Rate Limiting

Rate limiting controls how frequently events are delivered to prevent overwhelming your endpoints.

​

Format Examples

​

Use Cases

• High-volume topics: Prevent overwhelming downstream services
• Cost control: Limit API calls to external services
• Quality of service: Ensure consistent processing performance
• User experience: Avoid spamming users with too many notifications

​

Deduplication

Deduplication prevents duplicate event deliveries within a specified time window.

​

Format Examples

​

Use Cases

• Idempotent operations: Prevent duplicate charges, emails, or notifications
• Data consistency: Avoid processing the same event multiple times
• User experience: Prevent spam notifications
• Workflow stability: Ensure workflows are not triggered multiple times for the same event

​

Best Practices

​

Filter Design

When designing filters, it’s important to start simple by beginning with basic filters and adding complexity as needed. Test thoroughly to verify filters work as expected with sample events, and monitor performance since complex filters may impact processing speed. Additionally, use descriptive paths to make filter paths clear and meaningful for future maintenance and debugging.

​

Rate Limiting

When implementing rate limiting, know your limits by understanding your downstream service capacity. Start conservative by beginning with lower rates and increasing as needed, and consider peak times by accounting for traffic spikes in your rate limits.

​

Deduplication

When configuring deduplication, match your use case by using appropriate time windows for your business logic. Consider event timing by accounting for potential delays in event delivery, and balance safety and responsiveness since longer windows are safer but may delay legitimate retries. Finally, test deduplication behavior to ensure it works as expected with your event patterns.