Skip to content

docs: document Seerr requester in pre-deletion warnings and webhook mediaItems field #112

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
enoch85 merged 5 commits into from
Jul 18, 2026
Merged

docs: document Seerr requester in pre-deletion warnings and webhook mediaItems field #112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e3052b9
Initial plan
Copilot Jul 18, 2026
79f76bb
docs: document Seerr requester in pre-deletion warnings and webhook m…
Copilot Jul 18, 2026
713ccb9
docs: improve readability of notification type table and webhook vari…
Copilot Jul 18, 2026
6b7ada7
docs: fix trailing whitespace and clarify mediaItems type description
Copilot Jul 18, 2026
3f955f9
docs: fix prettier formatting in Notifications.md
Copilot Jul 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/Configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ Use your Emby server URL directly. Maintainerr supports either entering an API k

## Seerr

Seerr configuration is required if you want to use Seerr-related rule parameters or remove Seerr requests.
Seerr configuration is required if you want to use Seerr-related rule parameters, remove Seerr requests, or see who requested media in pre-deletion notifications.

| Setting | Description |
| ------- | ------------------------------------------------------------- |
Expand Down
41 changes: 32 additions & 9 deletions docs/Notifications.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,17 +37,21 @@ Each notification agent requires the following common settings:

Maintainerr supports several notification types that you can enable for each agent:

| Type | Description |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Media Added to Collection | Sent when media items are added to a collection |
| Media Removed from Collection | Sent when media items are removed from a collection |
| Media About to be Handled | Advance warning that media will be processed/deleted in X days |
| Media Handled | Confirmation that media has been processed/deleted |
| Rule Handling Failed | Alert when there's an error processing rules |
| Collection Handling Failed | Alert when there's an error processing collections. When Maintainerr can tie the failure to one collection, the message names that collection. |
| Type | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Media Added to Collection | Sent when media items are added to a collection |
| Media Removed from Collection | Sent when media items are removed from a collection |
| Media About to be Handled | Advance warning that media will be processed/deleted in X days. When Seerr is configured, the message also names the requester (see note below). |
| Media Handled | Confirmation that media has been processed/deleted |
| Rule Handling Failed | Alert when there's an error processing rules |
| Collection Handling Failed | Alert when there's an error processing collections. When Maintainerr can tie the failure to one collection, the message names that collection. |

Infrastructure-level collection failures that happen before Maintainerr can identify a specific collection still send the generic `Collection Handling Failed` message.

:::note Seerr requester in pre-deletion warnings
When Seerr (Overseerr or Jellyseerr) is configured, the **Media About to be Handled** message includes who requested the item — for example: _'Some Title' (requested by alice) will be handled in 3 days_. The lookup is season-aware for TV content and best-effort by design: if Seerr is unreachable or the item was not requested through Seerr, the requester line is silently omitted and the warning is still sent.
:::

## Supported Notification Agents

### Discord
Expand Down Expand Up @@ -213,7 +217,26 @@ The webhook agent supports variable replacement in the JSON payload. You can use
| `{{subject}}` | The notification subject/title |
| `{{message}}` | The notification message content |
| `{{image}}` | Associated image URL (if available) |
| `{{extra}}` | Additional data fields |
| `{{extra}}` | Additional data fields (see below) |

The `{{extra}}` block is also flattened into the top-level webhook payload as individual keys. The fields present depend on the notification type:

| Extra key | Type | Description |
| ---------------- | ------ | ----------------------------------------------------------- |
| `collectionName` | string | Name of the collection that triggered the notification |
| `dayAmount` | number | Days until the item is handled (`null` when not applicable) |
| `mediaItems` | string | Stringified JSON array of media items (see example below) |

Example `mediaItems` value for a **Media About to be Handled** notification when Seerr is configured:

```json
[
{ "mediaServerId": "abc123", "requestedBy": ["alice"] },
{ "mediaServerId": "def456" }
]
```

Each entry contains `mediaServerId`. The optional `requestedBy` array lists the Seerr usernames who requested the item; it is omitted when Seerr is not configured or the item was not requested there.

Example JSON payload:

Expand Down