feat: add webhook/non-polling based Plex media processing

[mmgoodnow]

Description

I started tracking metrics on how long it takes from the moment a show or movie is requested to the moment the user is notified it's available on Plex. One of the slowest parts of the pipeline is polling lag from Seerr polling Plex for new releases. This PR adds a new endpoint, allowing Plex/Tautulli/anyone to notify Seerr when new content is added via webhook.

Right now I have it set up so Tautulli pushes to Seerr. Tautulli holds a WebSocket connection to Plex so it already gets instant notifications. It is set up to wait ~15 seconds after seeing one episode, to wait for other episodes to settle, then it will send the HTTP request to Seerr.

In the future we could consider Seerr maintaining a similar WebSocket connection to Plex, which would mean everyone gets the benefit and no one has to configure Tautulli for it. I chose to implement the webhook method in this PR, which also lays groundwork for the WebSocket method if we were to want that in the future.

AI Disclosure: I used OpenAI Codex for the code in this PR. I have reviewed the code manually, and I have tested manually. All writing, other than the diff, is my own.

How Has This Been Tested?

I have been running it on my home instance. It cuts down time-to-email from ~3 minutes to 16 seconds, pretty consistently. You can see in the screenshot below. (15 of the 16 seconds is due to an intentional import delay in Tautulli, so it does not live in Seerr.)

Since this is net new code we don't have to worry about it causing bugs in other existing stuff.

Screenshots

I have a Grafana dashboard showing software-induced latency in my requested media pipeline. The red bars are what we're interested in, which answers the question: after something is available on Plex, how long until they receive the email notification that it's available?

At the top of this screenshot you can see downloads from before I added the webhook push. They routinely have latency of 2-5 minutes, because of the 5 minute polling interval.

Towards the bottom you can see downloads from after I added the webhook push.

Checklist:

• I have read and followed the contribution guidelines.
• Disclosed any use of AI (see our policy)
• I have updated the documentation accordingly. Updated OpenAPI yaml file.
• All new and existing tests passed.
• Successful build pnpm build
• Translation keys pnpm i18n:extract No translation keys were added.
• Database migration (if required) No database migration was required.

Summary by CodeRabbit

Release Notes

• New Features

  • Added Plex "Recently Added Processing" feature allowing external webhook tools (e.g., Tautulli) to trigger processing of newly added media items via a dedicated endpoint with required metadata.

• Documentation

  • Added comprehensive documentation for Recently Added Processing, including webhook configuration instructions, required authentication headers, and example templates for external tools.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a POST /plex/recently-added webhook endpoint to Seerr. PlexMetadata is extended with episode-level fields. PlexScanner gains a processRatingKey method that authenticates, fetches Plex metadata, and processes it. A new Express router handles the endpoint with admin auth, and matching OpenAPI spec and user docs are added.

Changes

Plex Recently Added Processing

Layer / File(s)	Summary
PlexMetadata contract and processRatingKey scanner method server/api/plexapi.ts, server/lib/scanners/plex/index.ts	PlexMetadata adds grandparentRatingKey, parentGuid, grandparentGuid, and episode to the type union. PlexScanner gains processRatingKey which authenticates with the admin Plex token, loads libraries, optionally syncs Hama anime data, fetches metadata for the given key, and runs processItem.
POST /recently-added route handler and wiring server/routes/plex.ts, server/routes/index.ts	New plexRoutes Express router adds POST /recently-added with ratingKey body validation, calls the scanner, returns { ratingKey, type, title } on success, and forwards 400/500 errors. The router is mounted at /plex with ADMIN auth in the main routes file.
OpenAPI spec and user documentation seerr-api.yml, docs/using-seerr/plex/index.md	OpenAPI spec documents the new endpoint with request schema and 200/400/500 responses. User docs add a "Recently Added Processing" feature entry and a webhook configuration guide including a Tautulli notification template.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• 0xSysR3ll
• fallenbagel
• M0NsTeRRR

Poem

🐇 Hop, hop! A new key arrives,
With ratingKey the scanner dives,
Tautulli whispers, Plex replies,
Metadata blooms before our eyes.
The rabbit cheers — new shows are found! 🎬

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main feature: adding webhook-based Plex media processing to eliminate polling.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@server/lib/scanners/plex/index.ts`:
- Around line 184-186: The processRatingKey method awaits processItem(metadata)
but processItem internally catches and suppresses errors, causing failures to be
silently ignored and allowing the webhook to return success status even when
processing fails. Remove the error suppression in the processItem method so that
errors are properly thrown and propagated up through processRatingKey to the
webhook handler, allowing proper error handling, retries, and alerts at the
caller level. If processItem catches errors intentionally for other code paths,
instead modify processRatingKey to detect and re-throw any processing failures
so the webhook path can receive accurate success or failure status.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f7b51668-03ba-43dc-b13c-b1405d1a5b12

📥 Commits

Reviewing files that changed from the base of the PR and between d2ffe4f and 712fdbb.

📒 Files selected for processing (6)

• docs/using-seerr/plex/index.md
• seerr-api.yml
• server/api/plexapi.ts
• server/lib/scanners/plex/index.ts
• server/routes/index.ts
• server/routes/plex.ts

[gauthier-th]

I don't understand the point of this PR.

You can already achieve this through the Seerr REST API: https://docs.seerr.dev/api/invoke-a-specific-job/
With the plex-recently-added-scan job.