Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Webhook or Watcher

Choose how CrossWatch receives playback activity from your media server.

Choose how CrossWatch receives playback activity from Plex, Jellyfin, or Emby.

Both sources can scrobble to Trakt, SIMKL, and MDBList. They differ in how events reach CrossWatch.

Recommendation

Use Watcher unless you have a specific reason to use Webhooks.

Watcher is managed in CrossWatch. It needs no inbound webhook URL and provides runtime controls.

Use Webhooks when the media server should push events to CrossWatch. They also suit reliable existing webhook deployments.

Watcher

Watcher reads playback activity from a configured media server profile.

Use Watcher when

  • CrossWatch can reach the media server API.

  • You want the simplest setup.

  • You need Start, Stop, Reload, or Autostart controls.

  • You use several source or destination profiles.

  • You need route-specific filters or completion options.

  • You do not want an exposed webhook endpoint.

How Watcher runs

Each route is one mapping:

source profile → destination profile

CrossWatch groups enabled routes by source profile.

For example, these routes share one Plex watcher:

  • Plex Home → Trakt Personal

  • Plex Home → SIMKL Personal

  • Plex Home → MDBList Personal

Each route still has its own destination, filters, and options.

Watcher considerations

  • CrossWatch must stay running.

  • The media server API must be reachable from CrossWatch.

  • Emby and Jellyfin detection uses session polling.

  • Stopped Watcher routes process nothing until restarted.

  • Enable Autostart to resume after a CrossWatch restart.

Webhooks

Webhooks let the media server send playback events to a generated CrossWatch URL.

Use Webhooks when

  • The media server can reach the CrossWatch URL.

  • The server or plugin delivers reliable playback events.

  • Push delivery is preferred over continuous monitoring.

  • A trusted reverse proxy provides a stable endpoint.

  • You need a provider-specific webhook workflow.

How Webhooks run

A media server profile receives one generated endpoint URL.

That profile can forward events to one or more tracker destinations.

CrossWatch shows each destination as a separate card. The source uses one shared endpoint URL.

Webhook considerations

  • The URL must be reachable from the media server.

  • localhost points to the media server, not usually CrossWatch.

  • Proxies, TLS, firewalls, and container networking can block delivery.

  • Media servers may reject self-signed certificates.

  • Regenerating the URL immediately invalidates the previous URL.

  • Source-profile filters and options affect every attached destination.

Feature comparison

Setup

Watcher

  • Create a route in CrossWatch.

  • Start Watcher.

  • No media server webhook configuration is needed.

Webhooks

  • Create a mapping in CrossWatch.

  • Copy the generated URL.

  • Configure that URL in the media server or plugin.

Network direction

Watcher: CrossWatch → media server

Webhooks: media server → CrossWatch

Runtime management

Watcher provides Start, Stop, Reload, Autostart, and route status.

Webhooks have no separate runtime service. They activate with a valid source, destination, and endpoint.

Filtering scope

Watcher filters are stored per route.

Webhook filters are stored per source profile. They affect every attached destination.

Per-destination behavior

Watcher supports route-specific filters, watchlist removal, watched thresholds, final-stop trust, and Plex ratings URLs.

Webhook playback options are shared by source profile. Mappings can still use different tracker profiles.

External requirements

Watcher needs no inbound URL or media server webhook feature.

Webhooks require a media server webhook feature or plugin. Availability and licensing differ by provider.

Can both be enabled?

Yes. Watcher and Webhooks can run together.

Do not send the same source playback to the same tracker profile through both methods.

Duplicate scrobbles are easy to create.

Safe hybrid examples

Separate media servers

  • Watcher: Plex → Trakt

  • Webhook: Jellyfin → SIMKL

Separate tracker profiles

  • Watcher: Plex Personal → Trakt Personal

  • Webhook: Plex Family → Trakt Family

Separate responsibilities

  • Watcher handles playback scrobbles.

  • A Plex ratings webhook handles ratings.

Avoid these combinations

  • Watcher: Plex Home → Trakt Personal

  • Webhook: Plex Home → Trakt Personal

The same title can send overlapping start, pause, stop, and completion events.

Avoid simultaneous playback from several users to one tracker profile. Most tracker accounts represent one active viewer.

Decision guide

Choose Watcher when any statement applies:

  1. You want the recommended configuration.

  2. You lack a trusted inbound URL.

  3. You need runtime controls.

  4. You need route-specific filters or options.

  5. You use several profiles.

Choose Webhooks when any statement applies:

  1. The media server already delivers reliable webhooks.

  2. CrossWatch cannot reliably monitor the media server.

  3. Push delivery is an operational requirement.

  4. CrossWatch has a trusted reverse proxy endpoint.

Migration from old webhooks

New webhook configuration uses profile-based URLs.

  1. Create a webhook mapping for the source profile.

  2. Copy its generated profile URL.

  3. Replace the old URL in the media server.

  4. Test playback.

  5. Remove legacy URLs from CrossWatch.

  6. Remove remaining old media server entries.

Related pages

PreviousScrobblerNextWebhooks

Last updated

Was this helpful?