Context
An SNS subscription filter decides which published messages a particular subscriber receives. The filter can inspect message attributes or JSON properties in the message body. Those are different locations. A publisher can include a field named eventType inside JSON while a subscription still looks for an attribute with that name, producing an apparently silent delivery gap.
Prepare a message contract sample
Record the topic ARN, subscription ARN, endpoint, filter policy, filter scope and publisher configuration. Obtain sanitized examples of the actual publish request, including attribute names and types as well as body shape. Confirm that the subscription is active before diagnosing selection behavior.
Choose test identifiers that can be followed to the receiving system without exposing message content. Define one event that should match and one that should not. This makes the intended filter contract reviewable before configuration changes begin.
1. Read scope and policy together
Inspect FilterPolicyScope with the filter policy. If no scope is specified, SNS uses MessageAttributes. Body filtering must be explicitly selected. Compare property names and values with the source selected by that scope rather than with an application object's internal representation.
Check the full JSON structure when body filtering is used. A field moved beneath another object is a contract change even if its value is unchanged. For attribute filtering, inspect the published data type and value rather than assuming the SDK serialized them as expected.
2. Evaluate the complete match
For each policy property, identify the corresponding published value and the matching condition. SNS ignores properties that are absent from the filter policy, but each specified property needs a qualifying match. Avoid reading a multi-property filter as though matching any one property is sufficient.
Keep the filter focused on routing requirements. Do not treat it as an authorization control for information that an untrusted recipient must never access. Topic permissions, publisher trust and subscriber access need their own review.
3. Use selection and delivery evidence separately
| Evidence | Boundary to inspect | Next action |
|---|---|---|
| All expected events are filtered out | Scope or property mismatch | Compare actual publish shape |
| Only one value is absent | Value or type condition | Reproduce that value in a test |
| Matching event selected but not consumed | Delivery or subscriber processing | Inspect endpoint and queue evidence |
| Tests vary just after a change | Configuration propagation | Retest after the documented window |
An explicitly illustrative scenario: an invoice publisher moves region into the JSON body during a release. Its subscription still uses the default attribute scope. The team captures the sanitized publish shape and chooses either to restore the attribute contract or explicitly migrate the filter to body scope. It tests both a matching invoice and an unrelated event before expanding the change to other subscribers.
Correct and verify the route
Apply the scoped policy or publisher correction in a test topic where practical. AWS documents that additions and changes can take up to fifteen minutes to fully take effect. Avoid repeatedly editing the policy while interpreting results from mixed propagation states.
After propagation, publish the approved matching and nonmatching samples with distinct IDs. Verify receipt at the subscription endpoint and completion in the consumer. Check that the nonmatching event is absent for the expected reason, rather than because all delivery has stopped.
The SOP should keep publisher schema, filter policy, scope, test samples and subscription owner together. Monitor filtered-out trends alongside delivery failures and consumer backlog. Review filters whenever publishers add nesting, rename fields or change attribute serialization. Routing is most dependable when every participating team shares the same message contract.
Explore Clouvenix managed infrastructure for implementation and operational handover.
Technical reference
SNS filter-policy semantics, filter scope, and subscription attributes define the selection behavior.