Message Filtering with SNS Subscription Filters

Q: What does SNS match a FilterPolicy against by default?

The MessageAttributes sent with Publish. Set FilterPolicyScope to MessageBody to match against JSON fields in the message body instead.

Q: What happens if a message doesn't match a subscriber's filter?

That subscriber simply does not receive it. The Publish call still succeeds and other subscribers whose filters do match still receive their copy.

Q: Can I filter on the message body instead of attributes?

Yes, set FilterPolicyScope to MessageBody on the subscription. The body must be valid JSON for the filter to evaluate its fields.

Fan-out delivers every message on a topic to every subscriber. Often that is too much - a billing queue only cares about payment events, a shipping queue only cares about fulfillment events, but both are subscribed to the same order-events topic.

Subscription filter policies solve this without splitting the topic. Each subscription gets its own FilterPolicy, and SNS only delivers messages that match it.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import json
 
sns.set_subscription_attributes(
    SubscriptionArn=sub_arn, AttributeName="FilterPolicy",
    AttributeValue=json.dumps({"eventType": ["payment"]}),
)

// --- TypeScript (AWS SDK v3) ---
import { SetSubscriptionAttributesCommand } from "@aws-sdk/client-sns";
 
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: subArn, AttributeName: "FilterPolicy",
  AttributeValue: JSON.stringify({ eventType: ["payment"] }),
}));

When to reach for this:

Several subscribers to one topic each need only a subset of the event types published.
You want to avoid a topic-per-event-type sprawl as your event catalog grows.
A high-volume topic would waste consumer capacity if every subscriber received every message.
You need to route by a business dimension (region, tier, event type) without changing the publisher.

Working Example

Publish messages with an eventType attribute to a topic with two SQS subscribers, each filtered to receive only its relevant event type.

# --- Python (boto3) ---
import boto3, json
 
sns = boto3.client("sns", region_name="us-east-1")
 
topic_arn = sns.create_topic(Name="order-events")["TopicArn"]
 
# 1. Subscribe both queues (ARNs assumed already looked up).
billing_sub = sns.subscribe(TopicArn=topic_arn, Protocol="sqs", Endpoint=billing_arn)["SubscriptionArn"]
shipping_sub = sns.subscribe(TopicArn=topic_arn, Protocol="sqs", Endpoint=shipping_arn)["SubscriptionArn"]
 
# 2. Give each subscription its own filter policy on the eventType attribute.
sns.set_subscription_attributes(
    SubscriptionArn=billing_sub, AttributeName="FilterPolicy",
    AttributeValue=json.dumps({"eventType": ["payment"]}))
sns.set_subscription_attributes(
    SubscriptionArn=shipping_sub, AttributeName="FilterPolicy",
    AttributeValue=json.dumps({"eventType": ["fulfillment"]}))
 
# 3. Publish two messages with different eventType attributes.
#    Each reaches only the subscriber whose filter matches.
sns.publish(TopicArn=topic_arn, Message="payment captured for o-100",
    MessageAttributes={"eventType": {"DataType": "String", "StringValue": "payment"}})
sns.publish(TopicArn=topic_arn, Message="o-100 shipped",
    MessageAttributes={"eventType": {"DataType": "String", "StringValue": "fulfillment"}})

// --- TypeScript (AWS SDK v3) ---
import {
  SNSClient, CreateTopicCommand, SubscribeCommand,
  SetSubscriptionAttributesCommand, PublishCommand,
} from "@aws-sdk/client-sns";
 
const sns = new SNSClient({ region: "us-east-1" });
 
const { TopicArn } = await sns.send(new CreateTopicCommand({ Name: "order-events" }));
 
// 1. Subscribe both queues (ARNs assumed already looked up).
const billing = await sns.send(new SubscribeCommand({ TopicArn, Protocol: "sqs", Endpoint: billingArn }));
const shipping = await sns.send(new SubscribeCommand({ TopicArn, Protocol: "sqs", Endpoint: shippingArn }));
 
// 2. Give each subscription its own filter policy on the eventType attribute.
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: billing.SubscriptionArn, AttributeName: "FilterPolicy",
  AttributeValue: JSON.stringify({ eventType: ["payment"] }),
}));
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: shipping.SubscriptionArn, AttributeName: "FilterPolicy",
  AttributeValue: JSON.stringify({ eventType: ["fulfillment"] }),
}));
 
// 3. Publish two messages with different eventType attributes.
//    Each reaches only the subscriber whose filter matches.
await sns.send(new PublishCommand({
  TopicArn, Message: "payment captured for o-100",
  MessageAttributes: { eventType: { DataType: "String", StringValue: "payment" } },
}));
await sns.send(new PublishCommand({
  TopicArn, Message: "o-100 shipped",
  MessageAttributes: { eventType: { DataType: "String", StringValue: "fulfillment" } },
}));

What this demonstrates:

Each subscription's FilterPolicy is independent - billing and shipping can have completely different rules on the same topic.
The filter matches against MessageAttributes by default, so publishers must send the attribute the policy tests.
A message that matches no filter on a subscription is simply not delivered there - the publish call still succeeds.
Adding a third differently-filtered subscriber requires no change to the two existing ones or to the publisher.

Deep Dive

FilterPolicy Structure

A filter policy is JSON where each key is an attribute name and the value is an array of conditions, all of which are ORed together for that key, with multiple keys ANDed together. Conditions can be exact strings, but also richer matchers:

# --- Python (boto3) ---
# Matches eventType in ["payment", "refund"] AND amount >= 100.
policy = json.dumps({
    "eventType": ["payment", "refund"],
    "amount": [{"numeric": [">=", 100]}],
})

// --- TypeScript (AWS SDK v3) ---
// Matches eventType in ["payment", "refund"] AND amount >= 100.
const policy = JSON.stringify({
  eventType: ["payment", "refund"],
  amount: [{ numeric: [">=", 100] }],
});

Other supported conditions include prefix matching ({"prefix": "us-"}), exists/does-not-exist checks, and anything-but exclusions ({"anything-but": ["test"]}). These let a subscriber express fairly specific routing rules without any custom logic in the publisher.

FilterPolicyScope: Attributes vs Body

By default, FilterPolicyScope is MessageAttributes - the filter matches against the MessageAttributes sent with Publish, not the message body itself. Setting it to MessageBody instead lets the filter match directly against JSON fields inside the published message body, which is convenient when the payload is already structured JSON and you do not want to duplicate fields into message attributes just for filtering.

# --- Python (boto3) ---
sns.set_subscription_attributes(
    SubscriptionArn=billing_sub, AttributeName="FilterPolicyScope", AttributeValue="MessageBody")

// --- TypeScript (AWS SDK v3) ---
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: billingSub, AttributeName: "FilterPolicyScope", AttributeValue: "MessageBody",
}));

Set the scope before or alongside the FilterPolicy itself - both are subscription attributes, and both must agree on where to look for the fields the policy references.

Filtering Reduces Consumer Load, Not Publisher Complexity

The publisher never needs to know who is subscribed or what they each want. It just publishes with enough attributes (or a rich enough body) for subscribers to filter on. This is the main structural benefit over one-topic-per-event-type: adding a new consumer interest is a subscription-side change only.

Gotchas

Publisher omits the attribute the filter checks - if eventType is never set on Publish, no subscriber whose filter requires it will ever match. Fix: always include the attributes your subscribers filter on, and consider a policy allowing "attribute does not exist" if that is intentional.
Mismatched FilterPolicyScope - a filter written for MessageBody fields does nothing if the subscription's scope is still MessageAttributes. Fix: set FilterPolicyScope to match how the filter policy is written.
Assuming a non-matching message errors - it does not. Publish succeeds regardless; the message is silently not delivered to non-matching subscribers. Fix: verify filters with test publishes and check delivery, not error absence.
Overly broad filters that match everything - defeats the purpose and re-creates the unfiltered fan-out load. Fix: review filter conditions to ensure they actually narrow the traffic each subscriber wants.
JSON body filters on non-JSON payloads - MessageBody scope requires the body to be valid JSON; a plain string body cannot be filtered this way. Fix: use MessageAttributes scope for non-JSON payloads.
Forgetting filters are per-subscription, not per-topic - assuming one filter policy applies topic-wide. Fix: set FilterPolicy on each subscription individually; there is no topic-level default.

Alternatives

Alternative	Use When	Don't Use When
Subscription filter policy (this page)	Several subscribers to one topic, each want a subset	Every subscriber genuinely needs every message
One topic per event type	Very few, stable event types	Event types grow often, causing topic sprawl
Consumer-side filtering	Filtering logic is too complex for FilterPolicy syntax	Discarding unwanted messages at the consumer wastes delivery cost
EventBridge rules	Complex routing across many AWS sources with rich event patterns	Simple SNS pub/sub already covers the need

FAQs

What does SNS match a FilterPolicy against by default?

The MessageAttributes sent with Publish. Set FilterPolicyScope to MessageBody to match against JSON fields in the message body instead.

What happens if a message doesn't match a subscriber's filter?

That subscriber simply does not receive it. The Publish call still succeeds and other subscribers whose filters do match still receive their copy.

Can a filter policy match more than exact string equality?

Yes. It supports arrays of values (OR), numeric range conditions, prefix matching, exists/does-not-exist, and anything-but exclusions, combined across multiple attribute keys with AND.

Do I need a different topic for each event type to filter?

No. That is exactly what filter policies avoid - one topic, multiple subscribers, each with its own filter policy scoped to the event types it cares about.

Can I filter on the message body instead of attributes?

Yes, set FilterPolicyScope to MessageBody on the subscription. The body must be valid JSON for the filter to evaluate its fields.

Is filtering applied per-topic or per-subscription?

Per-subscription. Each subscription has its own independent FilterPolicy, so different subscribers to the same topic can have entirely different rules.

SNS & SQS Together: Fan-Out Messaging - the unfiltered fan-out this narrows.
Messaging Deep Dive Basics - the base subscribe/publish/receive flow filters build on.
FIFO Topics & Queues - filter policies work on FIFO topics too.
SNS & SQS via SDK Best Practices - when to filter versus split topics.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Subscription filter policies solve this without splitting the topic. Each subscription gets its own FilterPolicy, and SNS only delivers messages that match it.

Recipe

Quick-reference recipe card - copy-paste ready.

# --- Python (boto3) ---
import json
 
sns.set_subscription_attributes(
    SubscriptionArn=sub_arn, AttributeName="FilterPolicy",
    AttributeValue=json.dumps({"eventType": ["payment"]}),
)

// --- TypeScript (AWS SDK v3) ---
import { SetSubscriptionAttributesCommand } from "@aws-sdk/client-sns";
 
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: subArn, AttributeName: "FilterPolicy",
  AttributeValue: JSON.stringify({ eventType: ["payment"] }),
}));

When to reach for this:

Several subscribers to one topic each need only a subset of the event types published.
You want to avoid a topic-per-event-type sprawl as your event catalog grows.
A high-volume topic would waste consumer capacity if every subscriber received every message.
You need to route by a business dimension (region, tier, event type) without changing the publisher.

Working Example

Publish messages with an eventType attribute to a topic with two SQS subscribers, each filtered to receive only its relevant event type.

# --- Python (boto3) ---
import boto3, json
 
sns = boto3.client("sns", region_name="us-east-1")
 
topic_arn = sns.create_topic(Name="order-events")["TopicArn"]
 
# 1. Subscribe both queues (ARNs assumed already looked up).
billing_sub = sns.subscribe(TopicArn=topic_arn, Protocol="sqs", Endpoint=billing_arn)["SubscriptionArn"]
shipping_sub = sns.subscribe(TopicArn=topic_arn, Protocol="sqs", Endpoint=shipping_arn)["SubscriptionArn"]
 
# 2. Give each subscription its own filter policy on the eventType attribute.
sns.set_subscription_attributes(
    SubscriptionArn=billing_sub, AttributeName="FilterPolicy",
    AttributeValue=json.dumps({"eventType": ["payment"]}))
sns.set_subscription_attributes(
    SubscriptionArn=shipping_sub, AttributeName="FilterPolicy",
    AttributeValue=json.dumps({"eventType": ["fulfillment"]}))
 
# 3. Publish two messages with different eventType attributes.
#    Each reaches only the subscriber whose filter matches.
sns.publish(TopicArn=topic_arn, Message="payment captured for o-100",
    MessageAttributes={"eventType": {"DataType": "String", "StringValue": "payment"}})
sns.publish(TopicArn=topic_arn, Message="o-100 shipped",
    MessageAttributes={"eventType": {"DataType": "String", "StringValue": "fulfillment"}})

// --- TypeScript (AWS SDK v3) ---
import {
  SNSClient, CreateTopicCommand, SubscribeCommand,
  SetSubscriptionAttributesCommand, PublishCommand,
} from "@aws-sdk/client-sns";
 
const sns = new SNSClient({ region: "us-east-1" });
 
const { TopicArn } = await sns.send(new CreateTopicCommand({ Name: "order-events" }));
 
// 1. Subscribe both queues (ARNs assumed already looked up).
const billing = await sns.send(new SubscribeCommand({ TopicArn, Protocol: "sqs", Endpoint: billingArn }));
const shipping = await sns.send(new SubscribeCommand({ TopicArn, Protocol: "sqs", Endpoint: shippingArn }));
 
// 2. Give each subscription its own filter policy on the eventType attribute.
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: billing.SubscriptionArn, AttributeName: "FilterPolicy",
  AttributeValue: JSON.stringify({ eventType: ["payment"] }),
}));
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: shipping.SubscriptionArn, AttributeName: "FilterPolicy",
  AttributeValue: JSON.stringify({ eventType: ["fulfillment"] }),
}));
 
// 3. Publish two messages with different eventType attributes.
//    Each reaches only the subscriber whose filter matches.
await sns.send(new PublishCommand({
  TopicArn, Message: "payment captured for o-100",
  MessageAttributes: { eventType: { DataType: "String", StringValue: "payment" } },
}));
await sns.send(new PublishCommand({
  TopicArn, Message: "o-100 shipped",
  MessageAttributes: { eventType: { DataType: "String", StringValue: "fulfillment" } },
}));

What this demonstrates:

Each subscription's FilterPolicy is independent - billing and shipping can have completely different rules on the same topic.
The filter matches against MessageAttributes by default, so publishers must send the attribute the policy tests.
A message that matches no filter on a subscription is simply not delivered there - the publish call still succeeds.
Adding a third differently-filtered subscriber requires no change to the two existing ones or to the publisher.

Deep Dive

FilterPolicy Structure

# --- Python (boto3) ---
# Matches eventType in ["payment", "refund"] AND amount >= 100.
policy = json.dumps({
    "eventType": ["payment", "refund"],
    "amount": [{"numeric": [">=", 100]}],
})

// --- TypeScript (AWS SDK v3) ---
// Matches eventType in ["payment", "refund"] AND amount >= 100.
const policy = JSON.stringify({
  eventType: ["payment", "refund"],
  amount: [{ numeric: [">=", 100] }],
});

FilterPolicyScope: Attributes vs Body

# --- Python (boto3) ---
sns.set_subscription_attributes(
    SubscriptionArn=billing_sub, AttributeName="FilterPolicyScope", AttributeValue="MessageBody")

// --- TypeScript (AWS SDK v3) ---
await sns.send(new SetSubscriptionAttributesCommand({
  SubscriptionArn: billingSub, AttributeName: "FilterPolicyScope", AttributeValue: "MessageBody",
}));

Set the scope before or alongside the FilterPolicy itself - both are subscription attributes, and both must agree on where to look for the fields the policy references.

Filtering Reduces Consumer Load, Not Publisher Complexity

Gotchas

Publisher omits the attribute the filter checks - if eventType is never set on Publish, no subscriber whose filter requires it will ever match. Fix: always include the attributes your subscribers filter on, and consider a policy allowing "attribute does not exist" if that is intentional.
Mismatched FilterPolicyScope - a filter written for MessageBody fields does nothing if the subscription's scope is still MessageAttributes. Fix: set FilterPolicyScope to match how the filter policy is written.
Assuming a non-matching message errors - it does not. Publish succeeds regardless; the message is silently not delivered to non-matching subscribers. Fix: verify filters with test publishes and check delivery, not error absence.
Overly broad filters that match everything - defeats the purpose and re-creates the unfiltered fan-out load. Fix: review filter conditions to ensure they actually narrow the traffic each subscriber wants.
JSON body filters on non-JSON payloads - MessageBody scope requires the body to be valid JSON; a plain string body cannot be filtered this way. Fix: use MessageAttributes scope for non-JSON payloads.
Forgetting filters are per-subscription, not per-topic - assuming one filter policy applies topic-wide. Fix: set FilterPolicy on each subscription individually; there is no topic-level default.

Alternatives

Alternative	Use When	Don't Use When
Subscription filter policy (this page)	Several subscribers to one topic, each want a subset	Every subscriber genuinely needs every message
One topic per event type	Very few, stable event types	Event types grow often, causing topic sprawl
Consumer-side filtering	Filtering logic is too complex for FilterPolicy syntax	Discarding unwanted messages at the consumer wastes delivery cost
EventBridge rules	Complex routing across many AWS sources with rich event patterns	Simple SNS pub/sub already covers the need

FAQs

What does SNS match a FilterPolicy against by default?

The MessageAttributes sent with Publish. Set FilterPolicyScope to MessageBody to match against JSON fields in the message body instead.

What happens if a message doesn't match a subscriber's filter?

That subscriber simply does not receive it. The Publish call still succeeds and other subscribers whose filters do match still receive their copy.

Can a filter policy match more than exact string equality?

Yes. It supports arrays of values (OR), numeric range conditions, prefix matching, exists/does-not-exist, and anything-but exclusions, combined across multiple attribute keys with AND.

Do I need a different topic for each event type to filter?

No. That is exactly what filter policies avoid - one topic, multiple subscribers, each with its own filter policy scoped to the event types it cares about.

Can I filter on the message body instead of attributes?

Yes, set FilterPolicyScope to MessageBody on the subscription. The body must be valid JSON for the filter to evaluate its fields.

Is filtering applied per-topic or per-subscription?

Per-subscription. Each subscription has its own independent FilterPolicy, so different subscribers to the same topic can have entirely different rules.

SNS & SQS Together: Fan-Out Messaging - the unfiltered fan-out this narrows.
Messaging Deep Dive Basics - the base subscribe/publish/receive flow filters build on.
FIFO Topics & Queues - filter policies work on FIFO topics too.
SNS & SQS via SDK Best Practices - when to filter versus split topics.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Message Filtering with SNS Subscription Filters

Buscar en la documentación

Message Filtering with SNS Subscription Filters