Subscription Scope Filters

Get to know how you can apply Subscription Scope Filters

What it is

A Subscription Scope Filter is a condition defined on a Subscription that controls which events a Subscriber receives based on the audiences field in the event.

Purpose

Subscription Scope Filters help ensure that Subscribers only receive events relevant to them—supporting multi-tenancy, reducing noise, and preventing data leaks.

How it works

When an event is published with an audiences value, Q-Flow checks if any Subscriptions have a matching Scope Filter. If there's a match, the event is delivered to that Subscription.

Example

Let’s say you have the following Subscription:

[
  {
    "id": "47fbf456-4711-4a77-a0eb-5db09d2fbd4f",
    "name": "ACME",
    "description": "ACME Subscription",
    "provisioningState": "Provisioned",
    "eventTypes": [
      {
        "id": "d43da7e4-7859-40bc-aa81-9f3e5bd87c6c",
        "type": "payment.authorized",
        "description": "The payment has been successfully authorized, meaning that the customer’s bank has approved the transaction, but the funds have not yet been transferred. This step typically occurs after the initial payment request, and it ensures that the amount can be charged."
      }
    ],
    "deadlettersCount": 0,
    "maxDeliveryAttempts": 5,
    "webhookUrl": "https://qala.q-flow.io",
    "audience": "ACME"
  }
]

Now, a Publisher sends this event:

{
    "type": "payment.authorized",
    "audiences": [
        "Qala",
        "ACME"
    ],
    "data": {
        "transactionId": "987654321",
        "paymentMethod": {
            "type": "credit_card",
            "last4": "4242",
            "brand": "Visa"
        },
        "amount": {
            "currency": "USD",
            "value": 600.00
        },
        "status": "authorized",
        "authorizedAt": "2025-02-07T12:34:56Z"
    }
}

✅ Because the event’s audiences matches the Subscription’s scopeFilter, the event is delivered.

❌ If the event had "audiences": "TenantACME", it would not be delivered to this Subscription.

Important Note

When publishing an event—whether using Publish Topic Events or the Publish Events—the event’s audiences field can include one or more alphanumeric values, or be left null. However, each Subscription can define only one alphanumeric audience within its Subscriber Scope Filter.

If a Subscription is created without a defined audience in its Scope Filter, it will receive all events that match its configured Event Types and any Advanced Query conditions—regardless of the event’s audience value. Think of the Subscription Scope Filter as an inclusion mechanism: it explicitly defines which audiences a Subscription should receive, rather than excluding others.