> 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/webhooks.md).

# Webhooks

Receive playback events from Plex, Jellyfin, or Emby. CrossWatch forwards them to Trakt, SIMKL, or MDBList.

A webhook mapping connects one media server profile to one tracker profile:

`source profile → destination profile`

CrossWatch generates the endpoint URL. The media server sends events to that URL.

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

### Before you start

1. Connect a Plex, Jellyfin, or Emby profile in **Settings → Connections**.
2. Connect a Trakt, SIMKL, or MDBList profile.
3. Confirm the media server can reach the CrossWatch address.
4. Use trusted HTTPS across untrusted networks.

Only configured profiles can be selected.

<figure><img src="/files/hcmhtqD4dIHML9GW7rYp" alt=""><figcaption></figcaption></figure>

### Add a webhook

1. Open **Settings → Scrobbler**.
2. Select **Add webhook**.
3. Select the source provider and profile.
4. Select the destination tracker and profile.
5. Configure filters, options, and Plex ratings if needed.
6. Select **Save changes**.
7. Copy the generated endpoint URL.
8. Add the URL to the media server configuration.
9. Start playback and check the card status.

The endpoint URL appears after the mapping is saved.

### Configure the media server

#### Plex

Add the generated Plex profile URL to Plex webhook configuration.

Use the same URL for playback and ratings when Plex ratings are enabled.

Webhook availability depends on Plex account and server features.

#### Jellyfin

Configure the Jellyfin webhook plugin with the generated Jellyfin profile URL.

Send playback start, pause, resume, and stop events. Choose JSON when available.

#### Emby

Configure the Emby webhook feature or plugin with the generated Emby profile URL.

Send playback start, pause, resume, and stop events.

Menu names vary by server and plugin version.

### Quick troubleshooting

* **No events:** Check the URL, host, port, certificate, and webhook event types.
* **Events ignored:** Check filters, source status, destination credentials, and Watcher duplication.
* **Duplicate scrobbles:** Use one source per source and destination profile pair.

See [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md) before running both sources.
{% endtab %}

{% tab title="Power users" %}

### Webhook modal

#### Source

Select the media server provider and profile. Then select the tracker and profile.

The source profile is fixed after creation. Delete and recreate the mapping to change it.

#### Filters

Every provider supports a username whitelist.

Plex also supports server UUID allowlists and blocklists.

See [Filters](broken://spaces/3rh5THg1PdhVsBt3GALo/pages/PH2jfcZjseHr6sFkoKAP).

#### Options

Webhook options inherit global defaults. Enable **Override global webhook defaults** to change them.

Overrides include pause debounce seconds and suppress start percent.

Overrides apply to every destination attached to the source profile.

#### Ratings

Plex sources can send ratings to Trakt, SIMKL, MDBList, or any combination.

Ratings settings are shared across the source profile's webhook destinations.

### Endpoint URL format

CrossWatch uses a profile token in every generated URL:

```
/webhook/plex?profile=<token>
/webhook/jellyfin?profile=<token>
/webhook/emby?profile=<token>
```

Always copy the full URL from **Scrobbler**. Do not build it manually.

The token identifies the source provider and profile. Treat the URL as a secret.

### One source profile, one endpoint

A source profile has one endpoint URL.

Several destinations can use it:

* Plex Home → Trakt Personal
* Plex Home → SIMKL Personal
* Plex Home → MDBList Personal

CrossWatch shows one card per destination. Plex Home uses one endpoint URL.

CrossWatch evaluates each event once, then sends it to configured destinations.

### Shared settings

These values are shared by every card using the same source profile:

* Endpoint URL
* Enabled state
* Filters
* Pause debounce override
* Suppress start override
* Plex ratings destinations

The tracker and tracker profile are specific to each card.

Disabling one card disables webhook processing for the complete source profile.

Editing filters or options changes all destination cards for that profile.

Deleting a card removes only its destination. Removing the final destination removes the profile webhook.

### Global webhook defaults

#### Pause debounce seconds

Default: `5`

CrossWatch ignores repeated pause events inside this period.

Increase it if one user action emits several pause events.

#### Suppress start percent

Default: `99`

CrossWatch ignores starts at or above this progress.

This prevents completed titles returning as actively playing.

### Filters

An empty filter accepts matching movie and episode events from the source profile.

Use filters for shared servers, selected users, or Plex events from another server UUID.

Webhook filters are profile-wide, not destination-specific.

### Enable, disable, and delete

The toggle controls the entire source profile webhook.

When disabled, the endpoint remains visible but ignores requests. Every card on that profile is disabled.

Reenable any card to reactivate the profile.

Deleting a card removes only its destination mapping.

When the final destination is removed, CrossWatch removes the profile mapping and endpoint token.

The Webhook source deactivates when no active mappings remain.

### Regenerate URL

Regenerate only when the endpoint token is exposed or needs rotation.

Regeneration affects the complete source profile.

1. Copy the new URL.
2. Replace the media server URL.
3. Test delivery.
4. Remove the old entry.

The old URL stops working immediately.

### Legacy URL cleanup

CrossWatch detects legacy Plex, Jellyfin, and Emby webhook tokens.

Use **Remove legacy URLs** only after every server uses its profile URL.

Cleanup permanently removes the old tokens.

### Status and troubleshooting

#### Card shows **Needs setup**

Confirm that source and destination profiles remain connected. Check destination credentials.

#### Events do not arrive

Check:

* The host resolves and is reachable from the media server.
* Protocol, port, and complete URL are correct.
* The proxy forwards the path and query string.
* The media server trusts the certificate.
* The source profile is enabled.
* The server sends playback event types.

Do not use `localhost` unless CrossWatch shares the media server network namespace.

#### Events arrive but are ignored

Check username and Plex UUID filters, profile state, destination credentials, and Watcher duplication.

Enable debug logging temporarily if normal logs lack a reason.

#### Duplicate scrobbles

Check whether the same source and tracker profile also use a Watcher route.

Use one event source for each source and destination combination.

### Related pages

* [Scrobbler](/crosswatch/settings/scrobbler.md)
* [Webhook or Watcher](/crosswatch/settings/scrobbler/webhook-or-watcher.md)
* [Watcher](/crosswatch/settings/scrobbler/watcher.md)
* [Filters](broken://spaces/3rh5THg1PdhVsBt3GALo/pages/PH2jfcZjseHr6sFkoKAP)
  {% 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/webhooks.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.