> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/settings/scrobbler/filters.md).

# Filters

Limit which playback events are accepted by a Watcher route or webhook source profile.

Filters are optional. An empty filter accepts every supported movie and episode visible to the selected source profile.

Start empty for the first test. Then add only the restrictions you need.

{% tabs %}
{% tab title="End users" %}

### Start simple

Start with empty filters. Confirm one movie or episode scrobbles correctly.

Then add only the restrictions you need.

With no filter values:

* All users are accepted.
* All Plex server UUID values are accepted.
* Plex Live TV and DVR are accepted by default.
* The selected source profile and library scope still apply.

### Filter scope

Watcher and Webhooks store filters differently.

#### Watcher filters

Watcher filters belong to each route. Two routes from one media server profile can use different filters.

For example:

* Plex Home → Trakt Pascal, with username `Pascal`
* Plex Home → Trakt Family, with username `Family`

#### Webhook filters

Webhook filters belong to the media server profile. Every tracker destination attached to that profile uses the same filter.

For example, Plex Home can send to both Trakt and SIMKL. Changing its webhook filter changes it for both destinations.

Use Watcher routes when each destination needs different filtering.

### Username whitelist

Use **Username whitelist** to accept playback only from selected users. Leave it empty to accept all users.

Use the user picker when possible. It uses names returned by the selected media server profile.

#### Common values

A normal entry is the visible media server username.

For Webhooks, use the picker or the exact username from incoming event logs.

### Plex Server UUID lists

Plex supports a Server UUID allowlist and blocklist.

Use the allowlist when only specific Plex servers may send events:

* An empty allowlist permits every UUID unless blocked.
* A populated allowlist requires a matching UUID.
* You can enter several UUID values.
* UUID matching is exact.

Use the fetch control in the modal when available.

Use the blocklist to reject specific Plex servers. The blocklist wins over the allowlist.

If a UUID appears in both lists, CrossWatch rejects the event.

A source profile selects a Plex connection. UUID filtering adds protection when multiple servers reach one listener or endpoint.

### Ignore Plex Live TV and DVR

This option is available for Plex Watcher routes.

Enable **Ignore Plex Live TV and DVR** to ignore playback identified as Plex Live TV or DVR content.

Webhook mappings do not show this option.

### Recommended patterns

#### Personal server with one user

Leave filters empty.

#### Shared server with one tracker account

Set **Username whitelist** to the tracker account owner.

#### Shared server with separate tracker accounts

Create one Watcher route per user and tracker profile. Use a different username whitelist on every route.

#### Several Plex servers

Use separate Plex profiles. Add a Server UUID allowlist when you need additional enforcement.

#### Ignore television broadcasts

Enable **Ignore Plex Live TV and DVR** on the relevant Plex Watcher routes.

### Troubleshooting

#### No events pass

1. Clear **Username whitelist**.
2. Clear Plex UUID allowlist and blocklist.
3. Disable **Ignore Plex Live TV and DVR** for testing.
4. Start a new playback session.
5. Check the source profile connection.
6. Review debug logs for the rejected field.

#### Wrong user is scrobbled

1. Use the user picker.
2. Verify the route or webhook scope.
3. Confirm the destination profile belongs to that user.
4. Check for another route or webhook without filters.

#### Wrong Plex server is accepted

1. Confirm the source profile.
2. Fetch the expected Server UUID.
3. Add it to the allowlist.
4. Add known unwanted UUID values to the blocklist.
5. Reload Watcher or retest the webhook.
   {% endtab %}

{% tab title="Power users" %}

### Matching behavior

Watcher username matching ignores letter case. It normalizes punctuation and spaces for normal names.

A nonmatching whitelist rejects the event. Without a username whitelist, the user filter passes.

Watcher also supports advanced identity values when the source event supplies them:

```
id:123
uuid:abcd1234
```

* `id:` compares account or user IDs.
* `uuid:` compares account or user UUID values.

Use advanced values only when normal username matching is ambiguous or unreliable.

Webhook implementations can expose different user fields. Use the event log’s exact username when the picker is unavailable.

### Profiles, filters, and libraries

Profiles and filters solve different problems.

A source profile selects the connected server or account configuration. Filters select which events from that profile CrossWatch accepts.

For example:

* Profile: Plex Home Server
* Username whitelist: Pascal
* Server UUID allowlist: Home Server UUID

Use profiles for connection separation. Use filters for event separation.

Filters do not replace media server library whitelisting.

Library whitelisting determines which libraries CrossWatch may use. Filters determine which incoming playback events are accepted.

Changing a username or UUID filter cannot bypass a library whitelist rejection.

### Common mistakes

#### Using a display name

The display name can differ from the event username. Use the picker or inspect incoming event logs.

#### Adding a Plex account ID without a prefix

Use:

```
id:123
```

Do not use:

```
123
```

The `id:` prefix is required for an ID match.

#### Expecting different webhook filters per destination

Webhook filters are shared by source profile. Use Watcher routes for destination-specific filtering.

#### Adding one UUID to both lists

The blocklist wins. CrossWatch rejects the event.

#### Filtering before the first test

Start with empty filters. Add restrictions after one movie or episode scrobbles correctly.

### Related pages

* [Scrobbler](/crosswatch/settings/scrobbler.md)
* [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md)
* [Webhooks](/crosswatch/settings/scrobbler/webhooks.md)
* [Watcher](/crosswatch/settings/scrobbler/watcher.md)
* [Library Whitelisting](/crosswatch/settings/connections/library-whitelisting.md)
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/settings/scrobbler/filters.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.