Merge branch 'develop-webhook-receiver' into develop

.env.sample

@@ -19,6 +19,36 @@ LOG_LEVEL=info
 # Generate with: openssl rand -hex 32
 COOKIE_SECRET=your-cookie-secret-here
 
+# =============================================================================
+# WEBHOOK SETTINGS
+# =============================================================================
+
+# Secret for validating incoming webhooks from Sonarr and Radarr
+# Required for webhook endpoints to accept requests
+# Sonarr/Radarr must send this secret in the X-Sofarr-Webhook-Secret header
+# Generate with: openssl rand -hex 32
+SOFARR_WEBHOOK_SECRET=your-webhook-secret-here
+
+# Public base URL of Sofarr (for webhook configuration)
+# Required for the one-click webhook setup endpoints
+# Sonarr/Radarr need this URL to know where to send webhook events
+# Example: https://sofarr.example.com or https://192.168.1.100:3001
+SOFARR_BASE_URL=https://your-sofarr-url
+
+# --- Webhook Polling Optimization (Phase 5) ---
+
+# Minutes of silence after which the poller falls back to a full poll
+# even if webhooks were recently active. Default: 10 minutes.
+# Set lower (e.g. 2) for more aggressive fallback; higher (e.g. 30) to
+# reduce background polling on very stable setups.
+# WEBHOOK_FALLBACK_TIMEOUT=10
+
+# When an instance has received a recent webhook event, the poller skips
+# its queue/history fetch entirely (saving API calls). If you still want
+# a periodic poll even with webhooks, set this to 1 to disable skipping.
+# Default behaviour: skip polling for instances with recent webhook activity.
+# WEBHOOK_POLL_INTERVAL_MULTIPLIER=3
+
 # =============================================================================
 # TLS / HTTPS
 # =============================================================================
@@ -136,4 +166,9 @@ RADARR_INSTANCES=[{"name":"main","url":"https://radarr.example.com","apiKey":"yo
 # 4. For qBittorrent, ensure Web UI is enabled in settings
 # 5. User downloads are matched by tags in Sonarr/Radarr - tag your media!
 # 6. Background polling keeps data fresh; disable it for low-resource setups
+# 7. Webhooks (SOFARR_WEBHOOK_SECRET + SOFARR_BASE_URL) enable real-time
+#    push updates from Sonarr/Radarr and automatically reduce polling load.
+#    Use the Webhooks Configuration panel in the dashboard UI to enable them
+#    with one click. The secret must match the header value in each *arr
+#    notification connection (X-Sofarr-Webhook-Secret).
 # =============================================================================

ARCHITECTURE.md

@@ -0,0 +1,927 @@
+# sofarr — Architecture
+
+Comprehensive technical reference for the **sofarr** application: a personal media download dashboard that aggregates download activity from SABnzbd, Sonarr, Radarr, qBittorrent, Transmission, and rTorrent, filters results by Emby/Jellyfin user identity, and presents a real-time personalised dashboard.
+
+---
+
+## Table of Contents
+
+1. [Introduction](#1-introduction)
+2. [High-Level Architecture](#2-high-level-architecture)
+3. [Pluggable Architecture Layers](#3-pluggable-architecture-layers)
+4. [Webhook System](#4-webhook-system)
+5. [Data Flow and Real-time Updates](#5-data-flow-and-real-time-updates)
+6. [Caching and Smart Polling](#6-caching-and-smart-polling)
+7. [Key Subsystems](#7-key-subsystems)
+8. [Directory Structure](#8-directory-structure)
+9. [Configuration and Environment Variables](#9-configuration-and-environment-variables)
+10. [Security Model](#10-security-model)
+11. [Technology Stack](#11-technology-stack)
+
+---
+
+## 1. Introduction
+
+sofarr is a **Node.js/Express single-page application** that provides a personalised view of media downloads. It:
+
+1. **Authenticates** users against an Emby/Jellyfin media server.
+2. **Aggregates** download data from multiple *arr service instances and download clients.
+3. **Filters** downloads per user — each user only sees media tagged with their username in Sonarr/Radarr.
+4. **Presents** a real-time dashboard with progress, speeds, cover art, and status, updated either via background polling or instant webhook push from Sonarr/Radarr.
+
+Admin users can view all users' downloads, see server status, cache statistics, poll timings, and perform blocklist-and-search operations.
+
+Three pluggable layers form the architectural core:
+
+| Layer | Name | Location |
+|-------|------|----------|
+| Download client abstraction | **PDCA** — Pluggable Download Client Architecture | `server/clients/` + `server/utils/downloadClients.js` |
+| *arr data retrieval | **PALDRA** — Pluggable *Arr Library Data Retrieval Architecture | `server/utils/arrRetrievers.js` |
+| Real-time push | **Webhook Receiver** | `server/routes/webhook.js` |
+
+---
+
+## 2. High-Level Architecture
+
+```mermaid
+flowchart TB
+    subgraph Browser["Browser (SPA — public/)"]
+        login["Login Form"]
+        dash["Dashboard Cards"]
+        status["Status Panel\n(Admin only)"]
+        history["History Tab"]
+    end
+
+    subgraph Server["Express Server (:3001)"]
+        direction TB
+        mw["Middleware\nHelmet · rate-limit · cookie-parser · verifyCsrf"]
+        auth_r["Auth Routes\n/api/auth"]
+        dash_r["Dashboard Routes\n/api/dashboard  (SSE /stream)"]
+        wh_r["Webhook Routes\n/api/webhook/sonarr|radarr"]
+        hist_r["History Routes\n/api/history"]
+        proxy_r["Proxy Routes\n/api/sonarr · /api/radarr\n/api/sabnzbd · /api/emby"]
+
+        subgraph Core["Core Utilities"]
+            poller["Poller\n(smart background polling)"]
+            cache["MemoryCache\n(poll:* + webhook metrics)"]
+            pdca["PDCA Registry\n(download clients)"]
+            paldra["PALDRA Registry\n(arr retrievers)"]
+            tokenstore["TokenStore\n(tokens.json)"]
+        end
+    end
+
+    subgraph Ext["External Services"]
+        sab["SABnzbd"]
+        sonarr["Sonarr"]
+        radarr["Radarr"]
+        qbt["qBittorrent"]
+        rtorrent["rTorrent"]
+        transmission["Transmission"]
+        emby["Emby / Jellyfin"]
+    end
+
+    login -->|"POST /api/auth/login"| auth_r
+    dash  -->|"GET /api/dashboard/stream (SSE)"| dash_r
+    status -->|"GET /api/dashboard/status"| dash_r
+    history -->|"GET /api/history/recent"| hist_r
+
+    auth_r --> tokenstore
+    auth_r -->|"authenticate"| emby
+
+    dash_r --> cache
+    dash_r --> poller
+    wh_r --> cache
+    wh_r --> paldra
+    hist_r --> cache
+    proxy_r -->|"proxy"| sonarr & radarr & sab & emby
+
+    poller --> pdca & paldra
+    poller --> cache
+    pdca -->|"HTTP/API"| sab & qbt & rtorrent & transmission
+    paldra -->|"HTTP/API"| sonarr & radarr
+
+    sonarr & radarr -->|"POST /api/webhook/*"| wh_r
+```
+
+### Request routing summary
+
+```
+Browser (SPA)
+    │  POST /api/auth/login          → Auth routes → Emby verify → set httpOnly cookie
+    │  GET  /api/dashboard/stream    → SSE stream → cache → matched downloads
+    │  POST /api/webhook/*           ← Sonarr/Radarr push events
+    │
+    ▼
+Express Server (:3001)
+    ├── Helmet (CSP nonce, HSTS, X-Frame-Options, …)
+    ├── express-rate-limit (300/15 min general; 60/1 min webhook; 10 fails/15 min login)
+    ├── cookie-parser (HMAC-signed session cookie)
+    ├── verifyCsrf (double-submit cookie, all state-changing /api routes except auth + webhook)
+    │
+    ├── /api/auth          → login, logout, me, csrf
+    ├── /api/webhook       → [rate-limit] → [secret validation] → [payload validation]
+    │                        → [replay check] → updateWebhookMetrics → processWebhookEvent
+    ├── /api/dashboard     → requireAuth → read cache → match downloads → SSE/JSON
+    ├── /api/history       → requireAuth → historyFetcher (5 min cache) → filter + dedup
+    ├── /api/sonarr|radarr → requireAuth → verifyCsrf → proxy to *arr API
+    └── /api/sabnzbd|emby  → requireAuth → verifyCsrf → proxy
+
+Background:
+    Poller (setInterval POLL_INTERVAL ms)
+        └── shouldSkipInstancePolling? ──yes──► extend cache TTL, increment pollsSkipped
+                │ no (or fallback triggered)
+                ▼
+            PDCA Registry.getDownloadsByClientType()
+            PALDRA Registry.getQueuesByType() / getHistoryByType() / getTagsByType()
+                │
+                ▼
+            cache.set('poll:*', data, TTL)
+                │
+                ▼
+            notify pollSubscribers → SSE push to all connected browsers
+```
+
+---
+
+## 3. Pluggable Architecture Layers
+
+### 3.1 Pluggable Download Client Architecture (PDCA)
+
+#### Overview
+
+The PDCA provides a unified, extensible interface for all download clients. This abstraction layer enables:
+
+- **Client-agnostic polling** — the poller contains no client-specific logic.
+- **Easy extension** — add a new client by implementing one interface.
+- **Consistent normalisation** — all clients return standardised download objects.
+- **Centralised configuration** — a single registry manages all instances.
+- **Error isolation** — individual client failures do not affect other clients.
+
+#### Abstract Base Class
+
+All download clients extend `DownloadClient` (`server/clients/DownloadClient.js`):
+
+```javascript
+class DownloadClient {
+  constructor(instanceConfig)
+  getClientType(): string
+  getInstanceId(): string
+  async testConnection(): Promise<boolean>
+  async getActiveDownloads(): Promise<NormalizedDownload[]>
+  async getClientStatus(): Promise<Object|null>   // optional
+  normalizeDownload(download): NormalizedDownload
+}
+```
+
+#### Client Implementations
+
+```
+DownloadClient (abstract)
+├── SABnzbdClient       — REST API, API key auth; handles queue + history; normalises time/size units
+├── QBittorrentClient   — Sync API (incremental deltas), cookie auth, fallback to /torrents/info
+├── TransmissionClient  — JSON-RPC, session-ID management
+└── RTorrentClient      — XML-RPC (xmlrpc 1.3.2), HTTP Basic Auth; maps rTorrent states to normalised statuses
+```
+
+#### Normalised Download Schema
+
+Every client returns objects conforming to this schema:
+
+```javascript
+interface NormalizedDownload {
+  id: string                    // Client-specific unique ID
+  title: string                 // Download title/name
+  type: 'usenet' | 'torrent'    // Download type
+  client: string                // Client identifier ('sabnzbd', 'qbittorrent', etc.)
+  instanceId: string            // Instance identifier
+  instanceName: string          // Instance display name
+  status: string                // Normalised status (Downloading, Seeding, etc.)
+  progress: number              // Progress percentage (0–100)
+  size: number                  // Total size in bytes
+  downloaded: number            // Downloaded bytes
+  speed: number                 // Current speed in bytes/sec
+  eta: number | null            // ETA in seconds, null if unknown
+  category?: string             // Download category (optional)
+  tags?: string[]               // Download tags (optional)
+  savePath?: string             // Save path (optional)
+  addedOn?: string              // Added timestamp (optional)
+  arrQueueId?: number           // Sonarr/Radarr queue ID (optional)
+  arrType?: 'series' | 'movie'  // Sonarr/Radarr type (optional)
+  raw?: any                     // Original client response (escape hatch)
+}
+```
+
+#### Registry (`server/utils/downloadClients.js`)
+
+`DownloadClientRegistry` manages all instances:
+
+```javascript
+class DownloadClientRegistry {
+  async initialize()                                     // Create clients from config
+  getAllClients(): DownloadClient[]
+  getClient(instanceId): DownloadClient
+  getClientsByType(type): DownloadClient[]
+  async getAllDownloads(): NormalizedDownload[]           // Fetch from all clients in parallel
+  async testAllConnections(): Promise<ConnectionTestResult[]>
+  async getAllClientStatuses(): Promise<ClientStatus[]>
+}
+```
+
+**Configuration-driven:** reads from `*_INSTANCES` environment variables (JSON array format) with fallback to legacy `*_URL` / `*_API_KEY` / `*_USERNAME` / `*_PASSWORD` variables.
+
+#### qBittorrent Sync API Details
+
+Each `QBittorrentClient` instance maintains:
+
+- **`lastRid`** — response ID from the previous `sync/maindata` call (starts at `0`).
+- **`torrentMap`** — `Map<hash, torrent>` holding the complete state for every known torrent.
+- **`fallbackThisCycle`** — boolean tracking whether this poll cycle has already fallen back to the legacy endpoint.
+
+Per-cycle flow:
+1. Attempt `GET /api/v2/sync/maindata?rid={lastRid}`.
+2. If `full_update` is `true`, rebuild `torrentMap` from scratch.
+3. Otherwise merge delta fields into existing entries; remove `torrents_removed` hashes.
+4. On Sync API failure, fall back **once per cycle** to `GET /api/v2/torrents/info`.
+5. If the fallback also fails, return an empty array for this cycle and log the error.
+
+The rest of the application (poller, dashboard) receives data in the same format regardless of which path was taken.
+
+#### Adding a New Download Client
+
+1. Create `server/clients/MyClient.js` extending `DownloadClient`.
+2. Implement `getActiveDownloads()` returning `NormalizedDownload[]`.
+3. Register the class in the registry factory inside `server/utils/downloadClients.js`.
+
+---
+
+### 3.2 Pluggable *arr Retrieval Layer (PALDRA)
+
+#### Overview
+
+`server/utils/arrRetrievers.js` exports `arrRetrieverRegistry`, a singleton that manages one `PollingSonarrRetriever` or `PollingRadarrRetriever` per configured instance. It provides a uniform interface for fetching queue, history, and tag data, keyed by service type.
+
+The registry is used by both the background poller and the webhook processor, guaranteeing consistent data shapes across both update paths.
+
+#### Registry API
+
+```javascript
+arrRetrieverRegistry = {
+  async initialize()                              // idempotent; reads config once
+  getAllRetrievers(): ArrRetriever[]
+  getRetriever(instanceId): ArrRetriever | null
+  getRetrieversByType(type): ArrRetriever[]       // 'sonarr' | 'radarr'
+
+  // Typed fetch methods — all return { sonarr: [...], radarr: [...] }
+  async getQueuesByType(): Promise<{ sonarr, radarr }>
+  async getHistoryByType(options?): Promise<{ sonarr, radarr }>
+  async getTagsByType(): Promise<{ sonarr, radarr }>
+}
+```
+
+Each result element is `{ instance: instanceId, data: <arr API response> }`, allowing callers to look up instance credentials from `config.js`.
+
+#### Retriever API Calls
+
+| Task | Endpoint | Key Parameters |
+|------|----------|----------------|
+| Sonarr tags | `GET /api/v3/tag` | — |
+| Sonarr queue | `GET /api/v3/queue` | `includeSeries=true`, `includeEpisode=true` |
+| Sonarr history | `GET /api/v3/history` | `pageSize=10`, `includeEpisode=true` |
+| Radarr tags | `GET /api/v3/tag` | — |
+| Radarr queue | `GET /api/v3/queue` | `includeMovie=true` |
+| Radarr history | `GET /api/v3/history` | `pageSize=10` |
+
+All fetches across all instances run in parallel via `Promise.allSettled`, so a single failing instance does not block others.
+
+---
+
+## 4. Webhook System
+
+### 4.1 Webhook Receiver
+
+sofarr exposes two webhook endpoints that Sonarr and Radarr can be configured to call on every automation event:
+
+```
+POST /api/webhook/sonarr
+POST /api/webhook/radarr
+```
+
+Both endpoints share identical processing logic:
+
+```
+Sonarr/Radarr
+    POST /api/webhook/sonarr
+    Headers: X-Sofarr-Webhook-Secret: <secret>
+    Body:    { "eventType": "Grab", "instanceName": "Main Sonarr",
+               "date": "2026-05-19T10:00:00.000Z", … }
+        │
+        ▼
+    webhookLimiter (60 req/min/IP)
+        │
+        ▼
+    validateWebhookSecret()  ──fail──► 401 Unauthorized
+        │ ok
+        ▼
+    validatePayload()        ──fail──► 400 Bad Request
+        │ ok
+        ▼
+    isReplay()               ──yes───► 200 { received: true, duplicate: true }
+        │ no
+        ▼
+    cache.updateWebhookMetrics(instance.url)   ← activates smart polling skip
+        │
+        ▼
+    200 { received: true }   ← response sent immediately
+        │
+        ▼  (fire-and-forget)
+    processWebhookEvent(serviceType, eventType)
+        ├── classify: QUEUE_EVENT or HISTORY_EVENT
+        ├── arrRetrieverRegistry.getQueuesByType() / getHistoryByType()
+        ├── cache.set('poll:sonarr-queue' | 'poll:sonarr-history', …, CACHE_TTL)
+        └── pollAllServices() → pollSubscribers.forEach(cb) → SSE push
+```
+
+The 200 response is sent **before** the background cache refresh completes, ensuring Sonarr/Radarr never have to wait for sofarr's downstream API calls.
+
+#### Event Classification
+
+| Event type | Classification | Cache keys refreshed |
+|------------|---------------|---------------------|
+| `Grab`, `Download`, `DownloadFailed`, `ManualInteractionRequired` | `QUEUE_EVENT` | `poll:{type}-queue` |
+| `DownloadFolderImported`, `ImportFailed`, `EpisodeFileRenamed`, `MovieFileRenamed`, `EpisodeFileRenamedBySeries` | `HISTORY_EVENT` | `poll:{type}-history` |
+| `Test`, `Rename`, `SeriesAdd`, `SeriesDelete`, `MovieAdd`, `MovieDelete`, `MovieFileDelete`, `Health`, `ApplicationUpdate`, `HealthRestored` | Informational — no refresh | — |
+
+#### Accepted Event Types
+
+The full allowlist enforced by `validatePayload()`:
+
+```
+Test · Grab · Download · DownloadFailed · ManualInteractionRequired
+DownloadFolderImported · ImportFailed
+EpisodeFileRenamed · MovieFileRenamed · EpisodeFileRenamedBySeries
+Rename · SeriesAdd · SeriesDelete · MovieAdd · MovieDelete · MovieFileDelete
+Health · ApplicationUpdate · HealthRestored
+```
+
+Any `eventType` not in this set is rejected with `400 Bad Request`.
+
+---
+
+### 4.2 Real-time Cache and SSE Integration
+
+When a webhook event is classified as a `QUEUE_EVENT` or `HISTORY_EVENT`:
+
+1. `arrRetrieverRegistry` fetches fresh data from the relevant *arr instances (in parallel, via PALDRA).
+2. The result is written directly into the shared `MemoryCache` under the same `poll:*` key the poller uses — ensuring both paths produce identical cache shapes.
+3. `pollAllServices()` is called, which iterates `pollSubscribers` and pushes the updated payload to every open SSE connection immediately.
+
+The dashboard therefore receives fresh data within the round-trip time of the *arr API call, without waiting for the next poll cycle.
+
+---
+
+### 4.3 Notification Management API
+
+The `sonarr.js` and `radarr.js` route modules expose endpoints (under `/api/sonarr` and `/api/radarr` respectively, behind `requireAuth` + `verifyCsrf`) for one-click webhook configuration. These proxy to the *arr notification API to create, update, or remove the sofarr webhook connection in Sonarr/Radarr, using `SOFARR_BASE_URL` to construct the target URL.
+
+---
+
+## 5. Data Flow and Real-time Updates
+
+### 5.1 Polling Cycle (background path)
+
+Every `POLL_INTERVAL` ms the poller fetches all services in parallel:
+
+| Task | API | Key parameters |
+|------|-----|----------------|
+| SABnzbd Queue | `GET /api?mode=queue` | `output=json` |
+| SABnzbd History | `GET /api?mode=history` | `limit=10` |
+| Sonarr Tags | `GET /api/v3/tag` | — |
+| Sonarr Queue | `GET /api/v3/queue` | `includeSeries=true`, `includeEpisode=true` |
+| Sonarr History | `GET /api/v3/history` | `pageSize=10`, `includeEpisode=true` |
+| Radarr Tags | `GET /api/v3/tag` | — |
+| Radarr Queue | `GET /api/v3/queue` | `includeMovie=true` |
+| Radarr History | `GET /api/v3/history` | `pageSize=10` |
+| qBittorrent | `GET /api/v2/sync/maindata?rid=N` | Fallback: `GET /api/v2/torrents/info` |
+
+Results are stored in `MemoryCache` under `poll:*` keys with TTL `POLL_INTERVAL × 3`. Per-task timings are recorded in `lastPollTimings` for the admin status panel.
+
+```mermaid
+sequenceDiagram
+    participant Entry as index.js
+    participant Poller
+    participant PDCA as PDCA Registry
+    participant PALDRA as PALDRA Registry
+    participant Cache as MemoryCache
+    participant SSE as SSE Subscribers
+
+    Entry->>Poller: startPoller()
+    loop Every POLL_INTERVAL ms
+        Poller->>Poller: polling flag check (skip if concurrent)
+        Poller->>PDCA: getDownloadsByClientType()
+        Poller->>PALDRA: getQueuesByType() / getHistoryByType() / getTagsByType()
+        PDCA-->>Poller: { sabnzbd, qbittorrent, rtorrent, transmission }
+        PALDRA-->>Poller: { sonarr: [...], radarr: [...] }
+        Poller->>Cache: set poll:* keys (TTL = POLL_INTERVAL × 3)
+        Poller->>SSE: notify all subscribers → push data: frame
+    end
+```
+
+### 5.2 Webhook Path (real-time update)
+
+```mermaid
+sequenceDiagram
+    participant Arr as Sonarr/Radarr
+    participant WH as /api/webhook/sonarr
+    participant Cache as MemoryCache
+    participant PALDRA as PALDRA Registry
+    participant SSE as SSE Subscribers
+
+    Arr->>WH: POST /api/webhook/sonarr { eventType, instanceName, date }
+    WH->>WH: validateSecret + validatePayload + isReplay
+    WH->>Cache: updateWebhookMetrics(instance.url)
+    WH-->>Arr: 200 { received: true }
+    Note over WH: fire-and-forget begins
+    WH->>PALDRA: getQueuesByType() or getHistoryByType()
+    PALDRA-->>WH: fresh arr data
+    WH->>Cache: set poll:sonarr-queue / poll:sonarr-history
+    WH->>SSE: pollAllServices() → push data: frame to all clients
+```
+
+### 5.3 SSE Stream
+
+When a browser opens `GET /api/dashboard/stream`:
+
+1. Server sets `Content-Type: text/event-stream`, disables buffering (`X-Accel-Buffering: no`).
+2. Immediately builds and sends the first payload (same matching logic as `/user-downloads`).
+3. Registers a callback with the poller's `onPollComplete` subscriber set.
+4. After every subsequent poll cycle (or webhook-triggered broadcast), the callback fires, rebuilds the payload, and writes a `data:` SSE frame.
+5. A 25-second heartbeat comment (`: heartbeat`) keeps the connection alive through proxies.
+6. On client disconnect: deregisters callback, stops heartbeat, removes from `activeClients` map.
+
+The browser's native `EventSource` API handles reconnection automatically on network interruption.
+
+### 5.4 Download Matching Pipeline
+
+For each connected user the server:
+
+1. Reads all `poll:*` keys from `MemoryCache`.
+2. Builds `seriesMap`, `moviesMap`, `sonarrTagMap`, and `radarrTagMap` from embedded objects in queue records.
+3. For each SABnzbd/qBittorrent download item, attempts matches in priority order: Sonarr queue → Radarr queue → Sonarr history → Radarr history.
+4. Title matching is a **bidirectional, case-insensitive substring match**: `rTitle.includes(dlTitle) || dlTitle.includes(rTitle)`.
+5. For each match, resolves the series/movie, extracts user tags, checks ownership.
+6. Returns only the requesting user's downloads (or all, if admin with `showAll=true`).
+
+```mermaid
+flowchart TD
+    Start(["Download item"]) --> SQ{"Sonarr QUEUE\nmatch (title)"}
+    SQ -->|yes| SQR["Resolve series · extract user tag"]
+    SQ -->|no| RQ{"Radarr QUEUE\nmatch (title)"}
+    RQ -->|yes| RQR["Resolve movie · extract user tag"]
+    RQ -->|no| SH{"Sonarr HISTORY\nmatch (title)"}
+    SH -->|yes| SHR["Resolve series via seriesId"]
+    SH -->|no| RH{"Radarr HISTORY\nmatch (title)"}
+    RH -->|yes| RHR["Resolve movie via movieId"]
+    RH -->|no| Skip(["Skip — unmatched"])
+
+    SQR & RQR & SHR & RHR --> Tagged{"Tag matches\nrequesting user?"}
+    Tagged -->|yes| Include(["Include in response"])
+    Tagged -->|no| Skip
+```
+
+#### Tag matching
+
+Users are matched to downloads via Sonarr/Radarr tags:
+
+1. **Exact match** — tag label (lowercased) === username (lowercased).
+2. **Sanitised match** — handles Ombi tag mangling: `sanitizeTagLabel()` converts to lowercase, replaces non-alphanumeric chars with hyphens, collapses runs, trims.
+
+#### Matched download object fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'series'`/`'movie'`/`'torrent'` | Media type |
+| `title` | string | Raw download title |
+| `coverArt` | string/null | Poster URL from *arr |
+| `status` | string | Download status |
+| `progress` | string | Percentage complete |
+| `size`/`mb`/`mbmissing` | string/number | Size info |
+| `speed` | string | Current download speed |
+| `eta` | string | Estimated time remaining |
+| `seriesName`/`movieName` | string | Friendly media title |
+| `episodes` | `{season, episode, title}[]` | Episodes covered (sorted); empty array if Sonarr has no data |
+| `allTags` | string[] | All resolved tag labels on the series/movie |
+| `matchedUserTag` | string/null | Tag label matching the requesting user |
+| `tagBadges` | `{label, matchedUser}[]`/undefined | (Admin `showAll` only) each tag classified against Emby user list |
+| `importIssues` | string[]/null | Import warning/error messages |
+| `canBlocklist` | boolean | `true` if the current user may blocklist this download |
+| `downloadPath` | string/null | (Admin) Download client path |
+| `targetPath` | string/null | (Admin) *arr target path |
+| `arrLink` | string/null | (Admin) Link to *arr web UI |
+| `arrQueueId` | number/null | (Admin) Sonarr/Radarr queue record id |
+| `arrType` | `'sonarr'`/`'radarr'`/null | (Admin) Which *arr service owns this queue entry |
+| `arrInstanceUrl` | string/null | (Admin) Base URL of the *arr instance |
+| `arrInstanceKey` | string/null | (Admin) API key for the *arr instance |
+| `arrContentId` | number/null | (Admin) `episodeId` or `movieId` for triggering a new search |
+| `arrContentType` | `'episode'`/`'movie'`/null | (Admin) Content type for search command |
+| `addedOn` | number/null | (qBittorrent) Unix timestamp when torrent was added |
+| `availableForUpgrade` | boolean/undefined | (History) `true` when outcome is `failed` but content is on disk |
+
+---
+
+## 6. Caching and Smart Polling
+
+### 6.1 Cache Layer
+
+`server/utils/cache.js` exports a singleton `MemoryCache` backed by a `Map`. Each entry carries an expiration timestamp. The cache is shared by the poller, webhook processor, and all route modules.
+
+```javascript
+class MemoryCache {
+  get(key): any
+  set(key, value, ttlMs)
+  invalidate(key)
+  clear()
+  getStats(): CacheStats          // per-key size, item count, TTL remaining
+
+  // Webhook metrics helpers
+  updateWebhookMetrics(instanceUrl)
+  getWebhookMetrics(instanceUrl): { eventsReceived, lastWebhookTimestamp, pollsSkipped }
+  getGlobalWebhookMetrics(): { lastGlobalWebhookTimestamp }
+}
+```
+
+### 6.2 Cache Keys
+
+| Key | Content | TTL |
+|-----|---------|-----|
+| `poll:sab-queue` | `{ slots, status, speed, kbpersec }` | `POLL_INTERVAL × 3` |
+| `poll:sab-history` | `{ slots }` | `POLL_INTERVAL × 3` |
+| `poll:sonarr-queue` | `{ records }` with embedded `series` objects + `_instanceUrl`/`_instanceKey` | `POLL_INTERVAL × 3` |
+| `poll:sonarr-history` | `{ records }` — lightweight, no embedded objects | `POLL_INTERVAL × 3` |
+| `poll:sonarr-tags` | `[{ instance, data: [{id, label}] }]` | `POLL_INTERVAL × 3` |
+| `poll:radarr-queue` | `{ records }` with embedded `movie` objects + `_instanceUrl`/`_instanceKey` | `POLL_INTERVAL × 3` |
+| `poll:radarr-history` | `{ records }` — lightweight | `POLL_INTERVAL × 3` |
+| `poll:radarr-tags` | `[{ instance, data: [{id, label}] }]` | `POLL_INTERVAL × 3` |
+| `poll:qbittorrent` | `[torrent, …]` | `POLL_INTERVAL × 3` |
+| `history:sonarr` | `[record, …]` flat array with `_instanceUrl`/`_instanceName` | 5 min |
+| `history:radarr` | `[record, …]` flat array with `_instanceUrl`/`_instanceName` | 5 min |
+| `emby:users` | `Map<lowerName, displayName>` | 60 s |
+
+When polling is disabled (`POLL_INTERVAL=0`), all `poll:*` TTLs fall back to **30 s** and data is fetched on-demand when the dashboard finds an empty cache entry.
+
+### 6.3 Background Polling Modes
+
+| Mode | `POLL_INTERVAL` | Behaviour |
+|------|----------------|-----------|
+| **Background** | `> 0` (e.g. `5000`) | Periodic fetch every N ms; SSE subscribers notified after each cycle |
+| **On-demand** | `0` / `off` / `false` | Fetch triggered by first dashboard request when cache is empty; cached 30 s |
+
+The poller uses a `polling` boolean flag to prevent concurrent cycles: if an interval fires while the previous poll is still running, the new invocation is skipped and logged.
+
+### 6.4 Smart Polling Optimisation
+
+When Sonarr/Radarr are configured to send webhooks to sofarr, the poller automatically reduces unnecessary API calls:
+
+```
+pollAllServices() called every POLL_INTERVAL ms:
+
+  globalMetrics = cache.getGlobalWebhookMetrics()
+  fallbackTriggered = lastGlobalWebhookTimestamp > WEBHOOK_FALLBACK_TIMEOUT ago
+
+  for each service type (sonarr, radarr):
+    shouldSkip = !fallbackTriggered
+                 && all instances have metrics.eventsReceived > 0
+                 && all instances have metrics.lastWebhookTimestamp within WEBHOOK_FALLBACK_TIMEOUT
+
+    if shouldSkip:
+      extend TTL of existing cached data        ← zero *arr API calls
+      increment metrics.pollsSkipped
+      log "[Poller] Skipping sonarr polling for N instance(s) with active webhooks"
+    else:
+      fetch from *arr APIs → update cache
+```
+
+**Effect:** zero *arr API calls per poll cycle when webhooks are active and recent. The poller automatically falls back to full polling after `WEBHOOK_FALLBACK_TIMEOUT` minutes of silence (default: 10 minutes), ensuring the dashboard remains accurate even if webhooks stop arriving.
+
+### 6.5 Active SSE Client Tracking
+
+SSE connections are tracked precisely in `activeClients` (a `Map` keyed by `${username}:${connectedAt}`): registered on connect, removed on disconnect. The admin status panel shows each connected user and their connection duration. The `type: 'sse'` field distinguishes SSE clients from other connection types.
+
+---
+
+## 7. Key Subsystems
+
+### 7.1 Download Clients
+
+See [Section 3.1](#31-pluggable-download-client-architecture-pdca) for full detail. The client hierarchy is:
+
+```
+DownloadClient (abstract — server/clients/DownloadClient.js)
+├── SABnzbdClient.js       — Usenet; REST; API key auth
+├── QBittorrentClient.js   — Torrent; Sync API + fallback; cookie auth
+├── TransmissionClient.js  — Torrent; JSON-RPC; session-ID management
+└── RTorrentClient.js      — Torrent; XML-RPC; HTTP Basic Auth
+```
+
+`server/utils/qbittorrent.js` is a legacy compatibility shim that delegates to `QBittorrentClient`.
+
+### 7.2 Queue & History Processing
+
+**`server/utils/historyFetcher.js`** fetches history records from all Sonarr/Radarr instances for a configurable date window. Results are cached under `history:sonarr` / `history:radarr` for 5 minutes. Exports `classifySonarrEvent` / `classifyRadarrEvent` (returns `'imported'` | `'failed'` | `'other'`) and `invalidateHistoryCache`.
+
+**`server/routes/history.js`** (`GET /api/history/recent`) returns recently completed (imported or failed) downloads filtered for the authenticated user. Supports `?days=N` (default `RECENT_COMPLETED_DAYS`, capped at 90) and `?showAll=true` for admins. Results are sorted newest first.
+
+**`server/routes/dashboard.js`** (`POST /api/dashboard/blocklist-search`) removes a Sonarr/Radarr queue item with `blocklist=true` and immediately triggers an `EpisodeSearch` or `MoviesSearch` command. Non-admin users may only blocklist when import issues are present, or (for qBittorrent only) the torrent is over 1 hour old with less than 100% availability.
+
+### 7.3 Dashboard & Frontend
+
+The frontend is a **vanilla JavaScript SPA** with no build step. All logic resides in `public/app.js`, styled by `public/style.css`, and structured by `public/index.html`. Three CSS themes are available via the `data-theme` attribute on `<html>` and persist in `localStorage`:
+
+- **Light** — Purple gradient header, white cards
+- **Dark** — Dark surfaces, muted accents
+- **Mono** — Monochrome, minimal colour
+
+#### UI state machine
+
+```mermaid
+stateDiagram-v2
+    [*] --> SplashScreen : Page load
+    SplashScreen --> CheckAuth : checkAuthentication()
+
+    state CheckAuth <<choice>>
+    CheckAuth --> LoginForm : No session
+    CheckAuth --> Dashboard : Valid session
+
+    LoginForm --> Dashboard : Auth success (fade transition)
+    Dashboard --> LoginForm : Logout (stopSSE)
+
+    state Dashboard {
+        [*] --> Rendering
+        Rendering --> Rendering : SSE message → renderDownloads()
+
+        state SSEConnection {
+            [*] --> Connecting
+            Connecting --> Connected : First message
+            Connected --> Reconnecting : Connection lost
+            Reconnecting --> Connected : Auto-reconnect
+            Connected --> Connecting : showAll toggled
+        }
+
+        state StatusPanel {
+            [*] --> Closed
+            Closed --> Open : Click Status (admin)
+            Open --> Closed : Click close
+            Open --> Open : 5s timer refresh
+        }
+    }
+```
+
+#### Key frontend functions
+
+| Function | Purpose |
+|----------|---------|
+| `checkAuthentication()` | On load: check session → show dashboard or login |
+| `handleLogin()` | Authenticate, fade login → splash → dashboard |
+| `startSSE()` | Open `EventSource` to `/stream`; handle incoming data |
+| `stopSSE()` | Close `EventSource` and cancel reconnect timer |
+| `renderDownloads()` | Diff-based card rendering (create/update/remove) |
+| `createDownloadCard()` | Build DOM for a single card; renders tag badges, import-issue badge, blocklist button |
+| `updateDownloadCard()` | Update existing card in-place (progress, speed, etc.) |
+| `handleBlocklistSearch()` | Confirm dialog → POST `/blocklist-search` → update button state |
+| `toggleStatusPanel()` | Show/hide admin status panel |
+| `renderStatusPanel()` | Build status HTML (server, polling, SSE clients, cache) |
+| `initThemeSwitcher()` | Light / Dark / Mono theme support |
+| `loadHistory()` | Fetch `/api/history/recent`, store raw items, call `renderHistory()` |
+| `renderHistory()` | Filter items by `ignoreAvailable` flag, render history cards |
+
+#### Tag badge rendering
+
+- **Regular user view** — a single accent-coloured badge showing the tag label that matched the current user's username (via `matchedUserTag`).
+- **Admin `showAll` view** — all tags on the download are rendered using `tagBadges[]`: tags with no matching Emby user → amber badge (leftmost); tags matched to a known Emby user → accent badge showing the Emby display name (rightmost).
+
+---
+
+## 8. Directory Structure
+
+```
+sofarr/
+├── server/
+│   ├── app.js                  Express app factory — imported by tests and index.js
+│   ├── index.js                Entry point: logging setup, server listen, poller start
+│   ├── clients/                PDCA — one file per download client + retriever
+│   │   ├── DownloadClient.js   Abstract base class for all download clients
+│   │   ├── QBittorrentClient.js
+│   │   ├── SABnzbdClient.js
+│   │   ├── TransmissionClient.js
+│   │   ├── RTorrentClient.js
+│   │   ├── PollingSonarrRetriever.js  PALDRA — Sonarr retriever
+│   │   └── PollingRadarrRetriever.js  PALDRA — Radarr retriever
+│   ├── routes/
+│   │   ├── auth.js             POST /login, GET /me, GET /csrf, POST /logout
+│   │   ├── dashboard.js        SSE /stream, /user-downloads, /user-summary, /status, /cover-art, /blocklist-search
+│   │   ├── history.js          GET /api/history/recent
+│   │   ├── webhook.js          POST /api/webhook/sonarr|radarr
+│   │   ├── sonarr.js           Sonarr API proxy + webhook management
+│   │   ├── radarr.js           Radarr API proxy + webhook management
+│   │   ├── emby.js             Emby API proxy
+│   │   └── sabnzbd.js          SABnzbd API proxy
+│   ├── middleware/
+│   │   ├── requireAuth.js      httpOnly cookie auth enforcement
+│   │   └── verifyCsrf.js       Double-submit CSRF check (timing-safe)
+│   └── utils/
+│       ├── arrRetrievers.js    PALDRA registry — Sonarr/Radarr fetch registry
+│       ├── cache.js            MemoryCache + webhook metrics helpers
+│       ├── config.js           Multi-instance config parser
+│       ├── downloadClients.js  PDCA registry + factory
+│       ├── historyFetcher.js   History fetch + event classification
+│       ├── logger.js           File logger (DATA_DIR/server.log)
+│       ├── poller.js           Smart background polling engine
+│       ├── qbittorrent.js      Legacy compatibility shim → QBittorrentClient
+│       ├── sanitizeError.js    Secret redaction from errors/logs
+│       └── tokenStore.js       Emby token store (JSON file, atomic writes, 31-day TTL)
+├── public/                     Static SPA (served by Express)
+│   ├── index.html              HTML shell: splash, login, dashboard
+│   ├── app.js                  All frontend logic
+│   ├── style.css               Themes, layout, responsive design
+│   ├── favicon.ico / *.png     Favicons
+│   └── images/                 Logo / splash screen assets
+├── tests/
+│   ├── README.md               Testing approach and coverage targets
+│   ├── setup.js                Global setup: isolated DATA_DIR, rate-limit bypass
+│   ├── unit/                   Pure unit tests (no HTTP)
+│   └── integration/            Supertest + nock integration tests
+├── .gitea/workflows/
+│   ├── ci.yml                  Security audit + test/coverage on every push/PR
+│   ├── build-image.yml         Docker image build and push
+│   ├── create-release.yml      Release tagging workflow
+│   ├── docs-check.yml          Markdown lint + Mermaid validation
+│   └── licence-check.yml       Production dependency licence check
+├── Dockerfile                  Multi-stage production image (node:22-alpine)
+├── docker-compose.yaml         Example compose deployment
+├── vitest.config.js            Test runner configuration with per-file coverage thresholds
+├── package.json                Dependencies and scripts
+├── ARCHITECTURE.md             This document
+├── SECURITY.md                 Threat model and hardening guide
+├── CHANGELOG.md                Version history
+└── .env.sample                 Annotated environment variable template
+```
+
+---
+
+## 9. Configuration and Environment Variables
+
+### 9.1 Core Server
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `PORT` | No | `3001` | Server listen port |
+| `NODE_ENV` | No | — | Set to `production` for production logging and startup validation |
+| `DATA_DIR` | No | `./data` | Directory for `tokens.json` and `server.log`. Must be writable. In Docker: `/app/data` (named volume). |
+| `COOKIE_SECRET` | No* | — | Signs all session cookies with HMAC-SHA256. **Strongly recommended in production** (server exits on startup if unset in `NODE_ENV=production`). Generate with `openssl rand -hex 32`. |
+| `TRUST_PROXY` | No | — | Express `trust proxy` setting. Set to `1` when behind a TLS-terminating reverse proxy (nginx, Caddy, Traefik) so `req.ip` and `req.secure` are correct. |
+| `LOG_LEVEL` | No | `info` | `debug`, `info`, `warn`, `error`, `silent` |
+| `RECENT_COMPLETED_DAYS` | No | `7` | Default lookback window for `/api/history/recent`. Overridable per-request via `?days=`. Capped at 90. |
+
+### 9.2 TLS / HTTPS
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `TLS_ENABLED` | No | `true` | Set to `false` to run plain HTTP (e.g. when TLS is terminated by a reverse proxy). |
+| `TLS_CERT` | No | `certs/snakeoil.crt` | Path to TLS certificate (PEM). Defaults to the bundled self-signed snakeoil certificate. |
+| `TLS_KEY` | No | `certs/snakeoil.key` | Path to TLS private key (PEM). |
+
+### 9.3 Webhook
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `SOFARR_WEBHOOK_SECRET` | Yes* | — | Shared secret validated on the `X-Sofarr-Webhook-Secret` header. Webhook endpoints reject all requests if this is not set. Generate with `openssl rand -hex 32`. |
+| `SOFARR_BASE_URL` | Yes* | — | Public base URL of this sofarr instance (e.g. `https://sofarr.example.com`). Used by the one-click webhook configuration endpoints to tell Sonarr/Radarr where to send events. |
+| `WEBHOOK_FALLBACK_TIMEOUT` | No | `10` | Minutes of silence after which the poller falls back to full polling even when webhooks were recently active. |
+
+### 9.4 Polling
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `POLL_INTERVAL` | No | `5000` | Background poll interval in ms. Set to `0`, `off`, or `false` to disable and use on-demand mode. |
+
+### 9.5 Emby
+
+| Variable | Required | Default | Description |
+|----------|:--------:|---------|-------------|
+| `EMBY_URL` | Yes | — | Emby/Jellyfin base URL (e.g. `https://emby.example.com`) |
+| `EMBY_API_KEY` | Yes | — | Emby API key — used by the poller to list users for tag badge classification |
+
+### 9.6 Service Instances
+
+All service instances support both a JSON array format (recommended) and a legacy single-instance format:
+
+| Variable | Required | Format |
+|----------|:--------:|--------|
+| `SONARR_INSTANCES` | Yes* | JSON array |
+| `SONARR_URL` + `SONARR_API_KEY` | Yes* | Legacy single-instance |
+| `RADARR_INSTANCES` | Yes* | JSON array |
+| `RADARR_URL` + `RADARR_API_KEY` | Yes* | Legacy single-instance |
+| `SABNZBD_INSTANCES` | Yes* | JSON array |
+| `SABNZBD_URL` + `SABNZBD_API_KEY` | Yes* | Legacy single-instance |
+| `QBITTORRENT_INSTANCES` | No | JSON array (uses `username`/`password` not `apiKey`) |
+| `RTORRENT_INSTANCES` | No | JSON array (URL must include the full XML-RPC path, e.g. `/RPC2`) |
+
+\* Either `*_INSTANCES` or the legacy pair is required for each service.
+
+#### JSON array instance format
+
+```json
+[
+  { "name": "main", "url": "https://sonarr.example.com", "apiKey": "your-api-key" },
+  { "name": "4k",   "url": "https://sonarr4k.example.com", "apiKey": "your-4k-api-key" }
+]
+```
+
+qBittorrent and rTorrent instances use `username` and `password` instead of `apiKey`.
+
+Each instance receives an `id` derived from `name` (or index if unnamed), used as the key in PDCA and PALDRA registries.
+
+---
+
+## 10. Security Model
+
+### 10.1 Authentication and Sessions
+
+| Concern | Mechanism |
+|---------|-----------|
+| **User authentication** | Emby credentials via `POST /Users/authenticatebyname`. A deterministic `DeviceId` (SHA-256 of username, first 16 chars) ensures Emby reuses the same session on every login. |
+| **Session cookie** | `httpOnly`, `sameSite: strict`, `secure` when `TRUST_PROXY` is set. Payload: `{ id, name, isAdmin }` only — the Emby `AccessToken` is **never** sent to the browser. Signed with HMAC when `COOKIE_SECRET` is set. |
+| **Token store** | Emby `AccessToken`s stored server-side in `DATA_DIR/tokens.json` (atomic writes, 31-day TTL, hourly pruning). Used only for server-side Emby logout. |
+| **Session validation** | `requireAuth` middleware on all `/api/dashboard`, `/api/history`, and proxy routes. Returns `401` if the cookie is absent, tampered, or schema-invalid. |
+| **CSRF protection** | Double-submit cookie pattern. `verifyCsrf` middleware compares the `csrf_token` cookie against the `X-CSRF-Token` request header using `crypto.timingSafeEqual`. Applied to all state-changing requests (`POST`, `PUT`, `PATCH`, `DELETE`) under `/api/*` except auth and webhook routes. |
+| **Remember-me** | `rememberMe: true` → persistent cookie, `Max-Age` 30 days. `rememberMe: false` → session cookie (expires on browser close). |
+
+### 10.2 Webhook Security
+
+| Concern | Mechanism |
+|---------|-----------|
+| **Secret validation** | Every webhook request must carry `X-Sofarr-Webhook-Secret` matching `SOFARR_WEBHOOK_SECRET`. Absent or wrong secret → `401`. Webhook endpoints function outside the CSRF middleware (they are not browser-initiated). |
+| **Rate limiting** | Dedicated `webhookLimiter`: 60 req/min per IP (stricter than the general 300 req/15 min limiter). |
+| **Payload validation** | `validatePayload()` enforces: JSON object body, `eventType` as a non-empty string ≤ 64 chars, `eventType` in the allowlist, `instanceName` as string if present. Rejects with `400` on any violation. |
+| **Replay protection** | `isReplay()` caches a composite key `{eventType}:{instanceName}:{date}` for 5 minutes. Duplicate events within that window are acknowledged with `200 { received: true, duplicate: true }` and not processed. |
+
+### 10.3 Additional Security Measures
+
+| Concern | Mechanism |
+|---------|-----------|
+| **Rate limiting** | 300 req/15 min general (all API routes); 10 failed attempts/15 min login limiter; 60 req/1 min webhook limiter. |
+| **Secret leakage** | `sanitizeError()` (`server/utils/sanitizeError.js`) redacts secrets from error messages and logs: URL query-param secrets (`apikey=`, `token=`), HTTP auth headers (`Authorization:`, `X-Emby-Authorization:`), Bearer tokens, and basic-auth credentials in URLs. |
+| **HTTP headers** | Helmet v7: CSP with per-request nonce (`crypto.randomBytes(16)` for inline styles/scripts), HSTS, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `Permissions-Policy`. |
+| **Body size** | `express.json` body limit: 64 KB. |
+| **Authorisation matrix** | Regular users see only their own downloads. Admins can view all users, see paths and *arr links, and blocklist any download. Non-admins can only blocklist when import issues exist or (for qBittorrent) the torrent is >1 h old with <100% availability. |
+| **Container security** | Docker image runs as the non-root `node` user (UID 1000). `/app/data` is owned by `node`. |
+
+---
+
+## 11. Technology Stack
+
+### Runtime and Framework
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Runtime | Node.js 22 (Alpine) | LTS; ESM-ready; V8 coverage built-in |
+| Framework | Express 4.x | HTTP server, routing, middleware |
+| HTTP client | axios 1.x | External API communication |
+| XML-RPC client | xmlrpc 1.3.2 | rTorrent communication |
+| Frontend | Vanilla JS + CSS | SPA, no build step required |
+| Containerisation | Docker multi-stage (node:22-alpine) | Non-root `node` user; minimal image |
+| Logging | Custom logger + `console.*` redirection | File + stdout with configurable levels |
+
+### Security Middleware
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `helmet` | 7.x | HTTP security headers (CSP nonce, HSTS, referrer policy, frame options) |
+| `express-rate-limit` | 7.x | General, login, and webhook rate limiters |
+| `cookie-parser` | 1.x | Signed cookie support (HMAC via `COOKIE_SECRET`) |
+
+### Auth and Session
+
+| Component | Technology | Details |
+|-----------|-----------|---------|
+| Identity provider | Emby / Jellyfin API | `POST /Users/authenticatebyname` |
+| Session cookie | `httpOnly` + `sameSite: strict` | Signed when `COOKIE_SECRET` is set |
+| CSRF protection | Double-submit cookie | `csrf_token` cookie + `X-CSRF-Token` header; `crypto.timingSafeEqual` |
+| Token store | JSON file (`DATA_DIR/tokens.json`) | Atomic writes, 31-day TTL, hourly pruning |
+
+### Testing
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| `vitest` | 4.x | Test runner with V8 coverage; per-file coverage thresholds in `vitest.config.js` |
+| `supertest` | 7.x | HTTP integration testing against the Express app factory |
+| `nock` | 14.x | HTTP interception at Node layer (compatible with CJS `require('axios')`) |
+
+### CI/CD
+
+| Workflow file | Trigger | Purpose |
+|---------------|---------|---------|
+| `ci.yml` | Every push / PR | `npm audit --audit-level=high` + full test suite with V8 coverage |
+| `build-image.yml` | Push to `release/**` or `develop` | Build and push Docker image to registry |
+| `create-release.yml` | Tag push (`v*`) | Generate release notes and create a Gitea release |
+| `docs-check.yml` | Push / PR touching `**.md` | Markdown lint + Mermaid diagram parse validation |
+| `licence-check.yml` | Push / PR touching `package.json` | Verify production dependency licences are MIT-compatible |

CHANGELOG.md

@@ -6,6 +6,63 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ---
 
+## [1.5.0] - 2026-05-19
+
+### Changed
+
+- **`ARCHITECTURE.md`** — consolidated the two existing architecture documents (root concise reference and `docs/ARCHITECTURE.md` deep-dive) into a single comprehensive reference at the project root. The merged document covers all 11 sections: Introduction, High-Level Architecture, Pluggable Architecture Layers (PDCA + PALDRA), Webhook System, Data Flow and Real-time Updates, Caching and Smart Polling, Key Subsystems, Directory Structure, Configuration and Environment Variables, Security Model, and Technology Stack. Includes full Mermaid diagrams for system overview, polling cycle, webhook path, UI state machine, and download matching pipeline.
+- **`docs/ARCHITECTURE.md`** — removed; content fully merged into root `ARCHITECTURE.md`.
+
+---
+
+## [1.4.0] - 2026-05-19
+
+### Added
+
+#### Webhook Integration (Phases 1–5.1)
+
+- **Webhook receiver endpoints** — `POST /api/webhook/sonarr` and `POST /api/webhook/radarr` accept push events from Sonarr and Radarr with shared-secret validation (`X-Sofarr-Webhook-Secret` header). Dashboard updates in < 1 second after any grab, import, or failure.
+- **Selective cache invalidation** — each incoming event is classified into *queue events* (`Grab`, `Download`, `DownloadFailed`, `ManualInteractionRequired`) or *history events* (`DownloadFolderImported`, `ImportFailed`, `EpisodeFileRenamed`, `MovieFileRenamed`). Only the affected cache key is refreshed via a lightweight re-poll of that instance, rather than a full poll cycle.
+- **SSE broadcast on webhook** — after refreshing the cache, `pollAllServices()` is called as a fire-and-forget, triggering an immediate SSE push to every connected browser.
+- **Notification management API proxy** — `GET /api/sonarr/api/v3/notification` and `POST /api/sonarr/api/v3/notification` (and Radarr equivalents) proxy the full *arr Notification API through sofarr with auth + CSRF enforcement.
+- **One-click webhook setup** — `POST /api/sonarr/webhook/enable` and `POST /api/radarr/webhook/enable` auto-configure the Sofarr webhook notification connection inside the respective *arr service. `POST /api/sonarr/webhook/test` and `/radarr/webhook/test` trigger a test event.
+- **Webhooks Configuration UI** — collapsible panel in the dashboard allowing users to enable, test, and view webhook status for each configured Sonarr/Radarr instance, with per-trigger type indicators showing which event types are active.
+- **`SOFARR_WEBHOOK_SECRET`** environment variable — required for webhook endpoints to accept requests. Generate with `openssl rand -hex 32`.
+- **`SOFARR_BASE_URL`** environment variable — public URL of sofarr, used by the one-click setup to tell Sonarr/Radarr where to POST events.
+
+#### Smart Polling Optimization (Phase 5)
+
+- **Webhook metrics tracking** — `cache.js` now maintains per-instance and global webhook metrics (`lastWebhookTimestamp`, `eventsReceived`, `pollsSkipped`) via `getWebhookMetrics()`, `updateWebhookMetrics()`, `incrementPollsSkipped()`, `getGlobalWebhookMetrics()`.
+- **Conditional poll skipping** — `poller.js` calls `shouldSkipInstancePolling()` before each Sonarr/Radarr fetch. If all instances of a type have received a webhook event within the fallback timeout window, their queue/history API calls are skipped entirely; existing cached data has its TTL extended instead.
+- **Webhook fallback** — if no webhook events have been received globally for `WEBHOOK_FALLBACK_TIMEOUT` minutes (default: 10), the poller forces a full poll regardless of per-instance state. Logged as `[Poller] Webhook fallback triggered`.
+- **Poll-skip logging** — logs `[Poller] Skipping sonarr/radarr polling for N instance(s) with active webhooks` when polling is skipped.
+- **`WEBHOOK_FALLBACK_TIMEOUT`** environment variable — minutes before fallback polling (default: `10`).
+- **`WEBHOOK_POLL_INTERVAL_MULTIPLIER`** environment variable — internal multiplier for TTL calculations when webhooks are active (default: `3`).
+- **Phase 5.1 metrics connection** — `webhook.js` calls `cache.updateWebhookMetrics(instance.url)` after every successfully validated event, activating the smart skip logic for that instance.
+
+#### Security Hardening (Phase 6)
+
+- **Dedicated webhook rate limiter** — 60 requests per minute per IP on `/api/webhook/*`, stricter than the global 300/15 min API limiter. Bypassed in tests via `SKIP_RATE_LIMIT=1`.
+- **Strict input validation** — `validatePayload()` rejects: non-object bodies, missing/non-string/overlong `eventType`, unrecognised event type values (allowlist of 18 known *arr event types), non-string `instanceName`. Returns `400` with a descriptive message.
+- **Replay protection** — `isReplay()` tracks recently-seen `(eventType, instanceName, date)` tuples in a `Map` with a 5-minute TTL. Duplicate events within the window return `200 { received: true, duplicate: true }` without triggering a cache refresh or SSE broadcast.
+- **35 new webhook integration tests** — cover secret validation (missing/wrong/unconfigured), payload validation (all invalid cases), replay protection, happy-path acceptance of all relevant event types, metrics increment, and secret-never-leaks assertions.
+
+#### Documentation (Phase 6)
+
+- **`README.md`** — updated architecture overview diagram, added Webhooks section with quick-setup guide, added PDCA/PALDRA/webhook architecture table, added Webhooks & Smart Polling env var section, added webhook API endpoints, updated test count.
+- **`CHANGELOG.md`** — this entry.
+- **`SECURITY.md`** — added webhook threat model rows, webhook-specific hardening checklist, and rate-limit table entry for webhook endpoints.
+- **`ARCHITECTURE.md`** (root) — new concise top-level architecture reference describing all pluggable layers and the full webhook + polling optimization flow.
+- **`.env.sample`** — added `WEBHOOK_FALLBACK_TIMEOUT` and `WEBHOOK_POLL_INTERVAL_MULTIPLIER` with explanatory comments; updated NOTES section.
+
+### Changed
+
+- `poller.js` — `pollAllServices()` now conditionally skips Sonarr/Radarr fetches when webhooks are active; extends TTL of existing cache entries instead of overwriting with empty data.
+- `cache.js` — exports four new webhook metrics helpers alongside the existing `MemoryCache` singleton.
+- `webhook.js` — imported `express-rate-limit`; added `validatePayload()`, `isReplay()`, `VALID_EVENT_TYPES` allowlist, `recentEvents` Map, and per-route `webhookLimiter` middleware.
+
+---
+
 ## [1.3.0] - 2026-05-17
 
 ### Added

README.md

@@ -4,6 +4,8 @@
 
 **sofarr** is a personal media download dashboard that aggregates and displays real-time download progress from all your media automation services. Named for the experience of checking what has downloaded "so far" while you wait comfortably on your "sofa" for Sonarr, Radarr, and your download clients to do their thing!
 
+Version 1.4.x adds **real-time webhook integration**: Sonarr and Radarr can push events directly to sofarr, eliminating polling latency and automatically reducing background API calls when webhooks are active.
+
 ## What It Does
 
 sofarr connects to your media stack and shows you a personalized view of:
@@ -12,27 +14,59 @@ sofarr connects to your media stack and shows you a personalized view of:
 - **Recently Completed** - History tab showing imported and failed downloads from Sonarr/Radarr with deduplication and upgrade-awareness
 - **User Matching** - Downloads are matched to you based on tags in Sonarr/Radarr
 - **Multi-Instance Support** - Connect to multiple instances of each service
+- **Webhook Push Updates** - Sonarr/Radarr push events instantly to sofarr; dashboard updates in < 1s after a grab or import
+- **Smart Polling** - Background polling automatically reduces (or skips) API calls for instances with active webhooks, with configurable fallback
 
 ## How It Works
 
 ### Architecture Overview
 
 ```
-┌─────────────┐     ┌──────────────┐     ┌─────────────────────────────┐
-│   Browser   │────▶│   sofarr     │────▶│  SABnzbd (Usenet downloads)   │
-│   (User)    │◀────│   Server     │     │  qBittorrent (Torrents)       │
-└─────────────┘     └──────────────┘     │  Transmission (Torrents)      │
-                       │                 │  rTorrent (Torrents)          │
-                       │                 │  Sonarr (TV management)       │
-                       │                 │  Radarr (Movie management)    │
-                       │                 │  Emby (User authentication)   │
-                       ▼                 └─────────────────────────────┘
-                ┌──────────────┐
-                │  Dashboard   │
-                │  Aggregator  │
-                └──────────────┘
+┌─────────────┐     ┌──────────────────────────────────────────────┐
+│   Browser   │────▶│               sofarr Server                 │
+│   (User)    │◀────│  Auth · Dashboard · History · Webhooks       │
+└─────────────┘     │                                              │
+   SSE push ◀───────│  Poller (smart: skips when webhooks active)  │
+                    │  Cache · PDCA Download Registry · PALDRA     │
+                    └───┬─────────────────────────┬────────────────┘
+                        │ polls (background)       │ receives webhooks
+                        ▼                          │
+         ┌──────────────────────────┐    ┌─────────▼───────────────────┐
+         │  Download Clients        │    │  *arr Services              │
+         │  SABnzbd (Usenet)        │    │  Sonarr  (TV management)    │
+         │  qBittorrent (Torrent)   │◀───│  Radarr  (Movie management) │
+         │  Transmission (Torrent)  │    └─────────────────────────────┘
+         │  rTorrent (Torrent)      │
+         └──────────────────────────┘
+                       │
+              Emby / Jellyfin
+              (User authentication)
 ```
 
+**Three pluggable layers power sofarr:**
+
+| Layer | Name | What it does |
+|-------|------|--------------|
+| Download clients | **PDCA** (Pluggable Download Client Architecture) | Normalised interface for SABnzbd, qBittorrent, Transmission, rTorrent; easy to add new clients |
+| *arr data retrieval | **PALDRA** (Pluggable *Arr Library Data Retrieval Architecture) | Unified fetch layer for Sonarr/Radarr queue, history, and tags across multiple instances |
+| Real-time push | **Webhook receiver** | Sonarr/Radarr POST events to sofarr; cache updated immediately; SSE pushes to browser in < 1s |
+
+### Webhooks
+
+When webhooks are configured, sofarr receives instant push notifications from Sonarr and Radarr whenever a download is grabbed, imported, failed, or renamed. The dashboard updates in under a second — no polling delay.
+
+**Quick setup:**
+1. Set `SOFARR_WEBHOOK_SECRET` and `SOFARR_BASE_URL` in your `.env`
+2. Open the sofarr dashboard → **Webhooks Configuration** panel
+3. Click **Enable** next to each Sonarr/Radarr instance
+4. sofarr auto-configures the notification connection inside each *arr service
+
+**Smart polling fallback:** Once webhooks are active, the background poller automatically skips queue/history API calls for those instances. If no webhook events arrive for `WEBHOOK_FALLBACK_TIMEOUT` minutes (default: 10), the poller resumes a full poll automatically.
+
+**Webhook endpoints** (no user authentication required — protected by `X-Sofarr-Webhook-Secret`):
+- `POST /api/webhook/sonarr` — receives Sonarr events
+- `POST /api/webhook/radarr` — receives Radarr events
+
 ### The Matching Process
 
 1. **User Authentication**: Login via Emby credentials
@@ -194,6 +228,17 @@ POLL_INTERVAL=5000                  # Background polling interval in ms (default
                                     # Set to 0 or "off" to disable (on-demand mode)
 ```
 
+### Webhooks & Smart Polling
+```bash
+# Required for webhook endpoints to accept events
+SOFARR_WEBHOOK_SECRET=your-secret   # Shared secret (generate: openssl rand -hex 32)
+SOFARR_BASE_URL=https://sofarr.example.com  # Public URL used by one-click setup
+
+# Optional tuning
+WEBHOOK_FALLBACK_TIMEOUT=10         # Minutes without a webhook before forcing a full poll (default: 10)
+WEBHOOK_POLL_INTERVAL_MULTIPLIER=3  # Internal multiplier used by the skip logic (default: 3)
+```
+
 ### Download Clients (PDCA)
 
 sofarr uses a **Pluggable Download Client Architecture (PDCA)** that provides a unified interface for all download clients. This enables consistent data normalization, easy addition of new client types, and centralized configuration management.
@@ -327,6 +372,20 @@ sofarr polls all configured services in the background and caches the results. D
 ### History
 - `GET /api/history/recent` — Recently completed downloads from Sonarr/Radarr history
 
+### Webhook Receiver (no user auth — protected by `X-Sofarr-Webhook-Secret`)
+- `POST /api/webhook/sonarr` — receive Sonarr webhook events
+- `POST /api/webhook/radarr` — receive Radarr webhook events
+
+### Webhook Management (requires auth + CSRF)
+- `GET /api/sonarr/api/v3/notification` — list Sonarr notification connections
+- `POST /api/sonarr/api/v3/notification` — create/update Sonarr notification connection
+- `GET /api/radarr/api/v3/notification` — list Radarr notification connections
+- `POST /api/radarr/api/v3/notification` — create/update Radarr notification connection
+- `POST /api/sonarr/webhook/enable` — one-click enable Sofarr webhook in Sonarr
+- `POST /api/radarr/webhook/enable` — one-click enable Sofarr webhook in Radarr
+- `POST /api/sonarr/webhook/test` — trigger a Sonarr test event
+- `POST /api/radarr/webhook/test` — trigger a Radarr test event
+
 ### Service APIs (proxy to your services)
 - `GET /api/sabnzbd/*` — SABnzbd API proxy
 - `GET /api/sonarr/*` — Sonarr API proxy
@@ -370,7 +429,7 @@ npm run test:coverage   # with V8 coverage report (outputs to coverage/)
 npm run test:ui         # interactive Vitest UI
 ```
 
-145 tests across 10 test files covering the security-critical paths: auth middleware, CSRF protection, secret sanitization, config parsing, token store, qBittorrent utilities, and history deduplication/classification. See [`tests/README.md`](tests/README.md) for design decisions and coverage targets.
+290 tests across 18 test files covering auth middleware, CSRF protection, secret sanitization, config parsing, token store, qBittorrent utilities, history deduplication/classification, download client architecture, webhook endpoint security, input validation, replay protection, and webhook metrics integration. See [`tests/README.md`](tests/README.md) for design decisions and coverage targets.
 
 ## Development
 

SECURITY.md

@@ -4,8 +4,10 @@
 
 | Version | Supported |
 |---------|-----------|
+| 1.4.x   | ✅ Yes    |
+| 1.3.x   | ✅ Yes    |
 | 1.2.x   | ✅ Yes    |
-| 1.1.x   | ✅ Yes    |
+| 1.1.x   | ❌ No     |
 | 1.0.x   | ❌ No     |
 | < 1.0   | ❌ No     |
 
@@ -35,6 +37,10 @@ users via Emby. The primary threat surface when exposed to the public internet:
 | Privilege escalation (container) | Non-root user (UID 1000), `no-new-privileges`, all caps dropped |
 | Unbounded log growth | Size-based rotation: 10 MB cap, 3 rotated files kept |
 | Dependency vulnerabilities | `npm audit --audit-level=high` in CI on every push |
+| Unauthorized webhook injection | `SOFARR_WEBHOOK_SECRET` required on `X-Sofarr-Webhook-Secret` header; 401 on mismatch |
+| Webhook payload injection | `validatePayload()` allowlists 18 known event types; rejects non-object bodies and overlong fields |
+| Webhook replay attacks | `isReplay()` tracks `(eventType, instanceName, date)` tuples for 5 minutes; duplicate events return `200 { duplicate: true }` without cache mutation |
+| Webhook flood / DoS | Dedicated rate limiter: 60 requests/min per IP on `/api/webhook/*` |
 
 ---
 
@@ -49,6 +55,15 @@ users via Emby. The primary threat surface when exposed to the public internet:
 - [ ] HTTPS enforced by the reverse proxy with a valid certificate
 - [ ] Firewall rules: only 443/80 open externally; 3001 not directly exposed
 
+### Webhook-Specific (if using webhook integration)
+
+- [ ] `SOFARR_WEBHOOK_SECRET` set to a random 32-byte hex string (`openssl rand -hex 32`)
+- [ ] `SOFARR_BASE_URL` set to the public HTTPS URL of sofarr (used by one-click setup)
+- [ ] Secret stored only in `.env` or Docker secret — never committed to source control
+- [ ] Rotate `SOFARR_WEBHOOK_SECRET` if you suspect it has been leaked; re-enable webhooks via the UI
+- [ ] Verify Sonarr/Radarr send the exact secret value in the `X-Sofarr-Webhook-Secret` header
+- [ ] Review webhook logs (`[Webhook] WARNING`) for repeated auth failures which may indicate probing
+
 ### Recommended
 
 - [ ] Reverse proxy: Nginx, Caddy, or Traefik with TLS termination
@@ -145,6 +160,7 @@ server {
 |----------|-------|
 | `POST /api/auth/login` | 10 failed attempts per 15 min per IP |
 | All `/api/*` routes | 300 requests per 15 min per IP |
+| `POST /api/webhook/*` | 60 requests per 1 min per IP (webhook-specific limiter, stricter than general) |
 
 ---
 

client/src/App.css

@@ -304,3 +304,158 @@ body {
     grid-template-columns: 1fr;
   }
 }
+
+/* Webhooks Section Styles */
+.webhooks-section {
+  background: white;
+  border-radius: 10px;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  margin-bottom: 20px;
+  overflow: hidden;
+}
+
+.webhooks-header {
+  padding: 20px 30px;
+  background: #f8f9fa;
+  border-bottom: 2px solid #e0e0e0;
+  cursor: pointer;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  transition: background 0.3s;
+}
+
+.webhooks-header:hover {
+  background: #f0f1f2;
+}
+
+.webhooks-header h2 {
+  color: #333;
+  font-size: 1.3rem;
+  margin: 0;
+}
+
+.webhooks-toggle {
+  font-size: 1.2rem;
+  color: #666;
+  transition: transform 0.3s;
+}
+
+.webhooks-toggle.expanded {
+  transform: rotate(180deg);
+}
+
+.webhooks-content {
+  padding: 20px 30px;
+}
+
+.webhook-instance {
+  padding: 20px 0;
+  border-bottom: 1px solid #e0e0e0;
+}
+
+.webhook-instance:last-child {
+  border-bottom: none;
+}
+
+.webhook-instance h3 {
+  color: #333;
+  font-size: 1.1rem;
+  margin-bottom: 15px;
+}
+
+.webhook-status {
+  display: flex;
+  align-items: center;
+  gap: 15px;
+  margin-bottom: 15px;
+}
+
+.status-indicator {
+  font-size: 1rem;
+  font-weight: 500;
+  padding: 5px 15px;
+  border-radius: 20px;
+}
+
+.status-indicator.enabled {
+  background: #e8f5e9;
+  color: #4caf50;
+}
+
+.status-indicator.disabled {
+  background: #f5f5f5;
+  color: #999;
+}
+
+.enable-webhook-btn {
+  padding: 8px 16px;
+  background: #667eea;
+  color: white;
+  border: none;
+  border-radius: 5px;
+  cursor: pointer;
+  font-size: 0.95rem;
+  transition: background 0.3s;
+}
+
+.enable-webhook-btn:hover {
+  background: #5568d3;
+}
+
+.enable-webhook-btn:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.test-webhook-btn {
+  padding: 8px 16px;
+  background: #f093fb;
+  color: white;
+  border: none;
+  border-radius: 5px;
+  cursor: pointer;
+  font-size: 0.95rem;
+  transition: background 0.3s;
+}
+
+.test-webhook-btn:hover {
+  background: #d97ed8;
+}
+
+.test-webhook-btn:disabled {
+  background: #ccc;
+  cursor: not-allowed;
+}
+
+.webhook-triggers {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 10px;
+  padding-top: 15px;
+  border-top: 1px solid #e0e0e0;
+}
+
+.trigger-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.trigger-label {
+  color: #666;
+  font-size: 0.9rem;
+}
+
+.trigger-value {
+  font-weight: 500;
+  font-size: 1.1rem;
+}
+
+.trigger-value.active {
+  color: #4caf50;
+}
+
+.trigger-value.inactive {
+  color: #999;
+}

client/src/App.jsx

@@ -10,9 +10,14 @@ function App() {
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState(null);
   const [sessions, setSessions] = useState([]);
+  const [webhookSectionExpanded, setWebhookSectionExpanded] = useState(false);
+  const [sonarrWebhook, setSonarrWebhook] = useState({ enabled: false, triggers: { onGrab: false, onDownload: false, onImport: false, onUpgrade: false } });
+  const [radarrWebhook, setRadarrWebhook] = useState({ enabled: false, triggers: { onGrab: false, onDownload: false, onImport: false, onUpgrade: false } });
+  const [webhookLoading, setWebhookLoading] = useState(false);
 
   useEffect(() => {
     fetchSessions();
+    fetchWebhookStatus();
   }, []);
 
   const fetchSessions = async () => {
@@ -67,6 +72,112 @@ function App() {
     return new Date(dateString).toLocaleString();
   };
 
+  const fetchWebhookStatus = async () => {
+    try {
+      // Fetch Sonarr notifications
+      try {
+        const sonarrResponse = await axios.get('/api/sonarr/notifications');
+        const sonarrSofarr = sonarrResponse.data.find(n => n.name === 'Sofarr');
+        setSonarrWebhook({
+          enabled: !!sonarrSofarr,
+          triggers: sonarrSofarr ? {
+            onGrab: sonarrSofarr.onGrab,
+            onDownload: sonarrSofarr.onDownload,
+            onImport: sonarrSofarr.onImport,
+            onUpgrade: sonarrSofarr.onUpgrade
+          } : { onGrab: false, onDownload: false, onImport: false, onUpgrade: false }
+        });
+      } catch (err) {
+        // Sonarr not configured or not accessible
+        setSonarrWebhook({ enabled: false, triggers: { onGrab: false, onDownload: false, onImport: false, onUpgrade: false } });
+      }
+
+      // Fetch Radarr notifications
+      try {
+        const radarrResponse = await axios.get('/api/radarr/notifications');
+        const radarrSofarr = radarrResponse.data.find(n => n.name === 'Sofarr');
+        setRadarrWebhook({
+          enabled: !!radarrSofarr,
+          triggers: radarrSofarr ? {
+            onGrab: radarrSofarr.onGrab,
+            onDownload: radarrSofarr.onDownload,
+            onImport: radarrSofarr.onImport,
+            onUpgrade: radarrSofarr.onUpgrade
+          } : { onGrab: false, onDownload: false, onImport: false, onUpgrade: false }
+        });
+      } catch (err) {
+        // Radarr not configured or not accessible
+        setRadarrWebhook({ enabled: false, triggers: { onGrab: false, onDownload: false, onImport: false, onUpgrade: false } });
+      }
+    } catch (err) {
+      console.error('Failed to fetch webhook status:', err);
+    }
+  };
+
+  const enableSonarrWebhook = async () => {
+    setWebhookLoading(true);
+    try {
+      await axios.post('/api/sonarr/notifications/sofarr-webhook');
+      await fetchWebhookStatus();
+    } catch (err) {
+      console.error('Failed to enable Sonarr webhook:', err);
+      alert('Failed to enable Sonarr webhook. Check console for details.');
+    } finally {
+      setWebhookLoading(false);
+    }
+  };
+
+  const enableRadarrWebhook = async () => {
+    setWebhookLoading(true);
+    try {
+      await axios.post('/api/radarr/notifications/sofarr-webhook');
+      await fetchWebhookStatus();
+    } catch (err) {
+      console.error('Failed to enable Radarr webhook:', err);
+      alert('Failed to enable Radarr webhook. Check console for details.');
+    } finally {
+      setWebhookLoading(false);
+    }
+  };
+
+  const testSonarrWebhook = async () => {
+    setWebhookLoading(true);
+    try {
+      const sonarrResponse = await axios.get('/api/sonarr/notifications');
+      const sonarrSofarr = sonarrResponse.data.find(n => n.name === 'Sofarr');
+      if (sonarrSofarr) {
+        await axios.post('/api/sonarr/notifications/test', { id: sonarrSofarr.id });
+        alert('Sonarr webhook test sent successfully!');
+      } else {
+        alert('Sofarr webhook not configured for Sonarr.');
+      }
+    } catch (err) {
+      console.error('Failed to test Sonarr webhook:', err);
+      alert('Failed to test Sonarr webhook. Check console for details.');
+    } finally {
+      setWebhookLoading(false);
+    }
+  };
+
+  const testRadarrWebhook = async () => {
+    setWebhookLoading(true);
+    try {
+      const radarrResponse = await axios.get('/api/radarr/notifications');
+      const radarrSofarr = radarrResponse.data.find(n => n.name === 'Sofarr');
+      if (radarrSofarr) {
+        await axios.post('/api/radarr/notifications/test', { id: radarrSofarr.id });
+        alert('Radarr webhook test sent successfully!');
+      } else {
+        alert('Sofarr webhook not configured for Radarr.');
+      }
+    } catch (err) {
+      console.error('Failed to test Radarr webhook:', err);
+      alert('Failed to test Radarr webhook. Check console for details.');
+    } finally {
+      setWebhookLoading(false);
+    }
+  };
+
   return (
     <div className="app">
       <header className="app-header">
@@ -178,6 +289,110 @@ function App() {
         </div>
       )}
 
+      <div className="webhooks-section">
+        <div className="webhooks-header" onClick={() => setWebhookSectionExpanded(!webhookSectionExpanded)}>
+          <h2>⚡ Webhooks Configuration</h2>
+          <span className={`webhooks-toggle ${webhookSectionExpanded ? 'expanded' : ''}`}>▼</span>
+        </div>
+        {webhookSectionExpanded && (
+          <div className="webhooks-content">
+            {webhookLoading && <div className="loading">Loading webhook status...</div>}
+            <div className="webhook-instance">
+              <h3>Sonarr</h3>
+              <div className="webhook-status">
+                <span className={`status-indicator ${sonarrWebhook.enabled ? 'enabled' : 'disabled'}`}>
+                  {sonarrWebhook.enabled ? '● Enabled' : '○ Disabled'}
+                </span>
+                {!sonarrWebhook.enabled && (
+                  <button onClick={enableSonarrWebhook} className="enable-webhook-btn" disabled={webhookLoading}>
+                    Enable Sofarr Webhooks
+                  </button>
+                )}
+                {sonarrWebhook.enabled && (
+                  <button onClick={testSonarrWebhook} className="test-webhook-btn" disabled={webhookLoading}>
+                    Test
+                  </button>
+                )}
+              </div>
+              {sonarrWebhook.enabled && (
+                <div className="webhook-triggers">
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Grab</span>
+                    <span className={`trigger-value ${sonarrWebhook.triggers.onGrab ? 'active' : 'inactive'}`}>
+                      {sonarrWebhook.triggers.onGrab ? '✓' : '✗'}
+                    </span>
+                  </div>
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Download</span>
+                    <span className={`trigger-value ${sonarrWebhook.triggers.onDownload ? 'active' : 'inactive'}`}>
+                      {sonarrWebhook.triggers.onDownload ? '✓' : '✗'}
+                    </span>
+                  </div>
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Import</span>
+                    <span className={`trigger-value ${sonarrWebhook.triggers.onImport ? 'active' : 'inactive'}`}>
+                      {sonarrWebhook.triggers.onImport ? '✓' : '✗'}
+                    </span>
+                  </div>
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Upgrade</span>
+                    <span className={`trigger-value ${sonarrWebhook.triggers.onUpgrade ? 'active' : 'inactive'}`}>
+                      {sonarrWebhook.triggers.onUpgrade ? '✓' : '✗'}
+                    </span>
+                  </div>
+                </div>
+              )}
+            </div>
+            <div className="webhook-instance">
+              <h3>Radarr</h3>
+              <div className="webhook-status">
+                <span className={`status-indicator ${radarrWebhook.enabled ? 'enabled' : 'disabled'}`}>
+                  {radarrWebhook.enabled ? '● Enabled' : '○ Disabled'}
+                </span>
+                {!radarrWebhook.enabled && (
+                  <button onClick={enableRadarrWebhook} className="enable-webhook-btn" disabled={webhookLoading}>
+                    Enable Sofarr Webhooks
+                  </button>
+                )}
+                {radarrWebhook.enabled && (
+                  <button onClick={testRadarrWebhook} className="test-webhook-btn" disabled={webhookLoading}>
+                    Test
+                  </button>
+                )}
+              </div>
+              {radarrWebhook.enabled && (
+                <div className="webhook-triggers">
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Grab</span>
+                    <span className={`trigger-value ${radarrWebhook.triggers.onGrab ? 'active' : 'inactive'}`}>
+                      {radarrWebhook.triggers.onGrab ? '✓' : '✗'}
+                    </span>
+                  </div>
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Download</span>
+                    <span className={`trigger-value ${radarrWebhook.triggers.onDownload ? 'active' : 'inactive'}`}>
+                      {radarrWebhook.triggers.onDownload ? '✓' : '✗'}
+                    </span>
+                  </div>
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Import</span>
+                    <span className={`trigger-value ${radarrWebhook.triggers.onImport ? 'active' : 'inactive'}`}>
+                      {radarrWebhook.triggers.onImport ? '✓' : '✗'}
+                    </span>
+                  </div>
+                  <div className="trigger-item">
+                    <span className="trigger-label">On Upgrade</span>
+                    <span className={`trigger-value ${radarrWebhook.triggers.onUpgrade ? 'active' : 'inactive'}`}>
+                      {radarrWebhook.triggers.onUpgrade ? '✓' : '✗'}
+                    </span>
+                  </div>
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+
       <footer className="app-footer">
         <p>Ensure your media is tagged with "user:username" in Sonarr/Radarr to match downloads to users.</p>
       </footer>

package.json

@@ -1,6 +1,6 @@
 {
   "name": "sofarr",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "A personal media download dashboard that shows your downloads 'so far' while you relax on the sofa waiting for your *arr services to finish",
   "main": "server/index.js",
   "scripts": {

server/app.js

@@ -19,6 +19,7 @@ const embyRoutes = require('./routes/emby');
 const dashboardRoutes = require('./routes/dashboard');
 const historyRoutes = require('./routes/history');
 const authRoutes = require('./routes/auth');
+const webhookRoutes = require('./routes/webhook');
 const verifyCsrf = require('./middleware/verifyCsrf');
 
 function createApp({ skipRateLimits = false } = {}) {
@@ -94,6 +95,7 @@ function createApp({ skipRateLimits = false } = {}) {
   // API routes
   app.use('/api', apiLimiter);
   app.use('/api/auth', authRoutes);
+  app.use('/api/webhook', webhookRoutes);
 
   // CSRF protection for all state-changing API requests below
   app.use('/api', verifyCsrf);

server/routes/radarr.js

@@ -4,6 +4,7 @@ const axios = require('axios');
 const router = express.Router();
 const requireAuth = require('../middleware/requireAuth');
 const sanitizeError = require('../utils/sanitizeError');
+const { getWebhookSecret, getSofarrBaseUrl } = require('../utils/config');
 
 router.use(requireAuth);
 
@@ -56,4 +57,150 @@ router.get('/movies', async (req, res) => {
   }
 });
 
+// Notification proxy routes (Phase 3)
+// GET /api/radarr/notifications - list all notifications
+router.get('/notifications', async (req, res) => {
+  try {
+    const response = await axios.get(`${process.env.RADARR_URL}/api/v3/notification`, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to fetch Radarr notifications', details: sanitizeError(error) });
+  }
+});
+
+// GET /api/radarr/notifications/:id - get specific notification
+router.get('/notifications/:id', async (req, res) => {
+  try {
+    const response = await axios.get(`${process.env.RADARR_URL}/api/v3/notification/${req.params.id}`, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to fetch Radarr notification', details: sanitizeError(error) });
+  }
+});
+
+// POST /api/radarr/notifications - create notification
+router.post('/notifications', async (req, res) => {
+  try {
+    const response = await axios.post(`${process.env.RADARR_URL}/api/v3/notification`, req.body, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to create Radarr notification', details: sanitizeError(error) });
+  }
+});
+
+// PUT /api/radarr/notifications/:id - update notification
+router.put('/notifications/:id', async (req, res) => {
+  try {
+    const response = await axios.put(`${process.env.RADARR_URL}/api/v3/notification/${req.params.id}`, req.body, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to update Radarr notification', details: sanitizeError(error) });
+  }
+});
+
+// DELETE /api/radarr/notifications/:id - delete notification
+router.delete('/notifications/:id', async (req, res) => {
+  try {
+    const response = await axios.delete(`${process.env.RADARR_URL}/api/v3/notification/${req.params.id}`, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to delete Radarr notification', details: sanitizeError(error) });
+  }
+});
+
+// POST /api/radarr/notifications/test - test notification
+router.post('/notifications/test', async (req, res) => {
+  try {
+    const response = await axios.post(`${process.env.RADARR_URL}/api/v3/notification/test`, req.body, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to test Radarr notification', details: sanitizeError(error) });
+  }
+});
+
+// GET /api/radarr/notifications/schema - get notification schema
+router.get('/notifications/schema', async (req, res) => {
+  try {
+    const response = await axios.get(`${process.env.RADARR_URL}/api/v3/notification/schema`, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to fetch Radarr notification schema', details: sanitizeError(error) });
+  }
+});
+
+// POST /api/radarr/notifications/sofarr-webhook - one-click Sofarr webhook setup
+router.post('/notifications/sofarr-webhook', async (req, res) => {
+  try {
+    const sofarrBaseUrl = getSofarrBaseUrl();
+    const webhookSecret = getWebhookSecret();
+
+    if (!sofarrBaseUrl) {
+      return res.status(400).json({ error: 'SOFARR_BASE_URL not configured' });
+    }
+    if (!webhookSecret) {
+      return res.status(400).json({ error: 'SOFARR_WEBHOOK_SECRET not configured' });
+    }
+
+    const webhookUrl = `${sofarrBaseUrl}/api/webhook/radarr`;
+
+    // Check if Sofarr webhook already exists
+    const listResponse = await axios.get(`${process.env.RADARR_URL}/api/v3/notification`, {
+      headers: { 'X-Api-Key': process.env.RADARR_API_KEY }
+    });
+    const existingNotification = listResponse.data.find(n => n.name === 'Sofarr');
+
+    const notificationPayload = {
+      name: 'Sofarr',
+      implementation: 'Webhook',
+      configContract: 'WebhookSettings',
+      fields: [
+        { name: 'url', value: webhookUrl },
+        { name: 'method', value: 'POST' },
+        { name: 'headers', value: [{ key: 'X-Sofarr-Webhook-Secret', value: webhookSecret }] }
+      ],
+      onGrab: true,
+      onDownload: true,
+      onImport: true,
+      onUpgrade: true,
+      onRename: false,
+      onHealthIssue: false,
+      onApplicationUpdate: false
+    };
+
+    if (existingNotification) {
+      // Update existing notification
+      const response = await axios.put(
+        `${process.env.RADARR_URL}/api/v3/notification/${existingNotification.id}`,
+        { ...notificationPayload, id: existingNotification.id },
+        { headers: { 'X-Api-Key': process.env.RADARR_API_KEY } }
+      );
+      res.json(response.data);
+    } else {
+      // Create new notification
+      const response = await axios.post(
+        `${process.env.RADARR_URL}/api/v3/notification`,
+        notificationPayload,
+        { headers: { 'X-Api-Key': process.env.RADARR_API_KEY } }
+      );
+      res.json(response.data);
+    }
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to configure Sofarr webhook', details: sanitizeError(error) });
+  }
+});
+
 module.exports = router;

server/routes/sonarr.js

@@ -4,6 +4,7 @@ const axios = require('axios');
 const router = express.Router();
 const requireAuth = require('../middleware/requireAuth');
 const sanitizeError = require('../utils/sanitizeError');
+const { getWebhookSecret, getSofarrBaseUrl } = require('../utils/config');
 
 router.use(requireAuth);
 
@@ -56,4 +57,150 @@ router.get('/series', async (req, res) => {
   }
 });
 
+// Notification proxy routes (Phase 3)
+// GET /api/sonarr/notifications - list all notifications
+router.get('/notifications', async (req, res) => {
+  try {
+    const response = await axios.get(`${process.env.SONARR_URL}/api/v3/notification`, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to fetch Sonarr notifications', details: sanitizeError(error) });
+  }
+});
+
+// GET /api/sonarr/notifications/:id - get specific notification
+router.get('/notifications/:id', async (req, res) => {
+  try {
+    const response = await axios.get(`${process.env.SONARR_URL}/api/v3/notification/${req.params.id}`, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to fetch Sonarr notification', details: sanitizeError(error) });
+  }
+});
+
+// POST /api/sonarr/notifications - create notification
+router.post('/notifications', async (req, res) => {
+  try {
+    const response = await axios.post(`${process.env.SONARR_URL}/api/v3/notification`, req.body, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to create Sonarr notification', details: sanitizeError(error) });
+  }
+});
+
+// PUT /api/sonarr/notifications/:id - update notification
+router.put('/notifications/:id', async (req, res) => {
+  try {
+    const response = await axios.put(`${process.env.SONARR_URL}/api/v3/notification/${req.params.id}`, req.body, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to update Sonarr notification', details: sanitizeError(error) });
+  }
+});
+
+// DELETE /api/sonarr/notifications/:id - delete notification
+router.delete('/notifications/:id', async (req, res) => {
+  try {
+    const response = await axios.delete(`${process.env.SONARR_URL}/api/v3/notification/${req.params.id}`, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to delete Sonarr notification', details: sanitizeError(error) });
+  }
+});
+
+// POST /api/sonarr/notifications/test - test notification
+router.post('/notifications/test', async (req, res) => {
+  try {
+    const response = await axios.post(`${process.env.SONARR_URL}/api/v3/notification/test`, req.body, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to test Sonarr notification', details: sanitizeError(error) });
+  }
+});
+
+// GET /api/sonarr/notifications/schema - get notification schema
+router.get('/notifications/schema', async (req, res) => {
+  try {
+    const response = await axios.get(`${process.env.SONARR_URL}/api/v3/notification/schema`, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    res.json(response.data);
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to fetch Sonarr notification schema', details: sanitizeError(error) });
+  }
+});
+
+// POST /api/sonarr/notifications/sofarr-webhook - one-click Sofarr webhook setup
+router.post('/notifications/sofarr-webhook', async (req, res) => {
+  try {
+    const sofarrBaseUrl = getSofarrBaseUrl();
+    const webhookSecret = getWebhookSecret();
+
+    if (!sofarrBaseUrl) {
+      return res.status(400).json({ error: 'SOFARR_BASE_URL not configured' });
+    }
+    if (!webhookSecret) {
+      return res.status(400).json({ error: 'SOFARR_WEBHOOK_SECRET not configured' });
+    }
+
+    const webhookUrl = `${sofarrBaseUrl}/api/webhook/sonarr`;
+
+    // Check if Sofarr webhook already exists
+    const listResponse = await axios.get(`${process.env.SONARR_URL}/api/v3/notification`, {
+      headers: { 'X-Api-Key': process.env.SONARR_API_KEY }
+    });
+    const existingNotification = listResponse.data.find(n => n.name === 'Sofarr');
+
+    const notificationPayload = {
+      name: 'Sofarr',
+      implementation: 'Webhook',
+      configContract: 'WebhookSettings',
+      fields: [
+        { name: 'url', value: webhookUrl },
+        { name: 'method', value: 'POST' },
+        { name: 'headers', value: [{ key: 'X-Sofarr-Webhook-Secret', value: webhookSecret }] }
+      ],
+      onGrab: true,
+      onDownload: true,
+      onImport: true,
+      onUpgrade: true,
+      onRename: false,
+      onHealthIssue: false,
+      onApplicationUpdate: false
+    };
+
+    if (existingNotification) {
+      // Update existing notification
+      const response = await axios.put(
+        `${process.env.SONARR_URL}/api/v3/notification/${existingNotification.id}`,
+        { ...notificationPayload, id: existingNotification.id },
+        { headers: { 'X-Api-Key': process.env.SONARR_API_KEY } }
+      );
+      res.json(response.data);
+    } else {
+      // Create new notification
+      const response = await axios.post(
+        `${process.env.SONARR_URL}/api/v3/notification`,
+        notificationPayload,
+        { headers: { 'X-Api-Key': process.env.SONARR_API_KEY } }
+      );
+      res.json(response.data);
+    }
+  } catch (error) {
+    res.status(500).json({ error: 'Failed to configure Sofarr webhook', details: sanitizeError(error) });
+  }
+});
+
 module.exports = router;

server/routes/webhook.js

@@ -0,0 +1,317 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+const express = require('express');
+const rateLimit = require('express-rate-limit');
+const { logToFile } = require('../utils/logger');
+const { getWebhookSecret, getSonarrInstances, getRadarrInstances } = require('../utils/config');
+const cache = require('../utils/cache');
+const arrRetrieverRegistry = require('../utils/arrRetrievers');
+const { pollAllServices, POLL_INTERVAL, POLLING_ENABLED } = require('../utils/poller');
+
+const router = express.Router();
+
+// Dedicated rate limiter for webhook endpoints — stricter than the global API limiter.
+// Sonarr/Radarr send at most one event per action; 60/min per IP is generous.
+// In tests, SKIP_RATE_LIMIT=1 raises the ceiling to effectively unlimited.
+const webhookLimiter = rateLimit({
+  windowMs: 60 * 1000,
+  max: process.env.SKIP_RATE_LIMIT ? Number.MAX_SAFE_INTEGER : 60,
+  standardHeaders: true,
+  legacyHeaders: false,
+  message: { error: 'Too many webhook requests' }
+});
+
+// Valid *arr eventType strings — used for strict input validation.
+const VALID_EVENT_TYPES = new Set([
+  'Test',
+  'Grab', 'Download', 'DownloadFailed', 'ManualInteractionRequired',
+  'DownloadFolderImported', 'ImportFailed',
+  'EpisodeFileRenamed', 'MovieFileRenamed', 'EpisodeFileRenamedBySeries',
+  'Rename', 'SeriesAdd', 'SeriesDelete', 'MovieAdd', 'MovieDelete',
+  'MovieFileDelete', 'Health', 'ApplicationUpdate', 'HealthRestored'
+]);
+
+// Replay protection — cache recently-seen (eventType+instanceName+timestamp) keys.
+// *arr sends a `date` field on every event; we use it as the replay key component.
+// TTL = 5 minutes; an event replayed after that window is considered fresh.
+const REPLAY_WINDOW_MS = 5 * 60 * 1000;
+const recentEvents = new Map();
+
+function pruneReplayCache() {
+  const cutoff = Date.now() - REPLAY_WINDOW_MS;
+  for (const [key, ts] of recentEvents) {
+    if (ts < cutoff) recentEvents.delete(key);
+  }
+}
+
+function isReplay(eventType, instanceName, eventDate) {
+  if (!eventDate) return false;
+  pruneReplayCache();
+  const key = `${eventType}:${instanceName || ''}:${eventDate}`;
+  if (recentEvents.has(key)) return true;
+  recentEvents.set(key, Date.now());
+  return false;
+}
+
+// Cache TTL mirrors poller.js logic: 3x poll interval when active, 30s when on-demand
+const CACHE_TTL = POLLING_ENABLED ? POLL_INTERVAL * 3 : 30000;
+
+// Event classification — determines which cache keys to refresh
+const QUEUE_EVENTS = new Set([
+  'Grab',
+  'Download',
+  'DownloadFailed',
+  'ManualInteractionRequired'
+]);
+
+const HISTORY_EVENTS = new Set([
+  'DownloadFolderImported',
+  'ImportFailed',
+  'EpisodeFileRenamed',
+  'MovieFileRenamed',
+  'EpisodeFileRenamedBySeries'
+]);
+
+/**
+ * Validate webhook secret from the X-Sofarr-Webhook-Secret header
+ * @param {Object} req - Express request object
+ * @returns {boolean} True if secret is valid, false otherwise
+ */
+function validateWebhookSecret(req) {
+  const expectedSecret = getWebhookSecret();
+  const providedSecret = req.get('X-Sofarr-Webhook-Secret');
+
+  if (!expectedSecret) {
+    logToFile('[Webhook] WARNING: SOFARR_WEBHOOK_SECRET not configured, rejecting webhook');
+    return false;
+  }
+
+  if (!providedSecret) {
+    logToFile('[Webhook] WARNING: Missing X-Sofarr-Webhook-Secret header');
+    return false;
+  }
+
+  if (providedSecret !== expectedSecret) {
+    logToFile('[Webhook] WARNING: Invalid webhook secret provided');
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Process a webhook event by refreshing the affected cache and broadcasting SSE.
+ * This is a fire-and-forget background task — callers must respond to the webhook
+ * sender before awaiting this function.
+ *
+ * Phase 2: lightweight refresh via arrRetrieverRegistry + cache update + SSE broadcast.
+ *
+ * @param {string} serviceType - 'sonarr' or 'radarr'
+ * @param {string} eventType   - the eventType from the *arr webhook payload
+ */
+async function processWebhookEvent(serviceType, eventType) {
+  const affectsQueue = QUEUE_EVENTS.has(eventType);
+  const affectsHistory = HISTORY_EVENTS.has(eventType);
+
+  if (!affectsQueue && !affectsHistory) {
+    logToFile(`[Webhook] Event ${eventType} does not affect queue or history, skipping refresh`);
+    return;
+  }
+
+  logToFile(`[Webhook] ${serviceType} event "${eventType}" → queue=${affectsQueue}, history=${affectsHistory}`);
+
+  // Ensure retrievers are initialized (idempotent)
+  await arrRetrieverRegistry.initialize();
+
+  if (serviceType === 'sonarr') {
+    const sonarrInstances = getSonarrInstances();
+
+    if (affectsQueue) {
+      const queuesByType = await arrRetrieverRegistry.getQueuesByType();
+      const sonarrQueues = queuesByType.sonarr || [];
+      cache.set('poll:sonarr-queue', {
+        records: sonarrQueues.flatMap(q => {
+          const inst = sonarrInstances.find(i => i.id === q.instance);
+          const url = inst ? inst.url : null;
+          const key = inst ? inst.apiKey : null;
+          return (q.data.records || []).map(r => {
+            if (r.series) r.series._instanceUrl = url;
+            r._instanceUrl = url;
+            r._instanceKey = key;
+            return r;
+          });
+        })
+      }, CACHE_TTL);
+      logToFile(`[Webhook] Refreshed poll:sonarr-queue (${sonarrQueues.length} instance(s))`);
+    }
+
+    if (affectsHistory) {
+      const historyByType = await arrRetrieverRegistry.getHistoryByType({ pageSize: 10 });
+      const sonarrHistories = historyByType.sonarr || [];
+      cache.set('poll:sonarr-history', {
+        records: sonarrHistories.flatMap(h => h.data.records || [])
+      }, CACHE_TTL);
+      logToFile(`[Webhook] Refreshed poll:sonarr-history (${sonarrHistories.length} instance(s))`);
+    }
+  } else if (serviceType === 'radarr') {
+    const radarrInstances = getRadarrInstances();
+
+    if (affectsQueue) {
+      const queuesByType = await arrRetrieverRegistry.getQueuesByType();
+      const radarrQueues = queuesByType.radarr || [];
+      cache.set('poll:radarr-queue', {
+        records: radarrQueues.flatMap(q => {
+          const inst = radarrInstances.find(i => i.id === q.instance);
+          const url = inst ? inst.url : null;
+          const key = inst ? inst.apiKey : null;
+          return (q.data.records || []).map(r => {
+            if (r.movie) r.movie._instanceUrl = url;
+            r._instanceUrl = url;
+            r._instanceKey = key;
+            return r;
+          });
+        })
+      }, CACHE_TTL);
+      logToFile(`[Webhook] Refreshed poll:radarr-queue (${radarrQueues.length} instance(s))`);
+    }
+
+    if (affectsHistory) {
+      const historyByType = await arrRetrieverRegistry.getHistoryByType({ pageSize: 10 });
+      const radarrHistories = historyByType.radarr || [];
+      cache.set('poll:radarr-history', {
+        records: radarrHistories.flatMap(h => h.data.records || [])
+      }, CACHE_TTL);
+      logToFile(`[Webhook] Refreshed poll:radarr-history (${radarrHistories.length} instance(s))`);
+    }
+  }
+
+  // Broadcast to all SSE subscribers using the same mechanism poller.js uses.
+  // pollAllServices() refreshes all data, updates every cache key, and then
+  // iterates pollSubscribers to push fresh payloads to every open SSE connection.
+  // If a poll is already in progress this call is a no-op, but the cache keys
+  // above were already updated so the next broadcast (or dashboard request)
+  // will see fresh data.
+  logToFile('[Webhook] Triggering SSE broadcast via pollAllServices()');
+  await pollAllServices();
+}
+
+/**
+ * Validate and sanitize the incoming webhook payload.
+ * Returns { valid, eventType, instanceName, eventDate } or { valid: false, reason }.
+ */
+function validatePayload(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return { valid: false, reason: 'Payload must be a JSON object' };
+  }
+  const { eventType, instanceName } = body;
+  if (typeof eventType !== 'string' || eventType.length === 0 || eventType.length > 64) {
+    return { valid: false, reason: 'eventType must be a non-empty string (max 64 chars)' };
+  }
+  if (!VALID_EVENT_TYPES.has(eventType)) {
+    return { valid: false, reason: `Unknown eventType: ${eventType}` };
+  }
+  if (instanceName !== undefined && typeof instanceName !== 'string') {
+    return { valid: false, reason: 'instanceName must be a string if provided' };
+  }
+  const eventDate = body.date || null;
+  return { valid: true, eventType, instanceName: instanceName || null, eventDate };
+}
+
+/**
+ * POST /api/webhook/sonarr
+ * Receives webhook events from Sonarr instances.
+ * Validates the secret, logs the event, refreshes cache, broadcasts SSE, and returns 200.
+ *
+ * Phase 2: integrated with PALDRA cache + SSE for real-time dashboard updates.
+ * Phase 6: rate limiting, input validation, replay protection.
+ */
+router.post('/sonarr', webhookLimiter, (req, res) => {
+  if (!validateWebhookSecret(req)) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  const validation = validatePayload(req.body);
+  if (!validation.valid) {
+    logToFile(`[Webhook] Sonarr payload rejected: ${validation.reason}`);
+    return res.status(400).json({ error: validation.reason });
+  }
+
+  const { eventType, instanceName, eventDate } = validation;
+
+  if (isReplay(eventType, instanceName, eventDate)) {
+    logToFile(`[Webhook] Sonarr duplicate event ignored: ${eventType} @ ${eventDate}`);
+    return res.status(200).json({ received: true, duplicate: true });
+  }
+
+  try {
+    logToFile(`[Webhook] Sonarr event received - Type: ${eventType}, Instance: ${instanceName || 'unknown'}`);
+    logToFile(`[Webhook] Sonarr payload: ${JSON.stringify(req.body)}`);
+
+    // Phase 5.1: update webhook metrics for polling optimization
+    const sonarrInstances = getSonarrInstances();
+    const instance = sonarrInstances.find(i => i.name === instanceName);
+    if (instance) {
+      cache.updateWebhookMetrics(instance.url);
+    }
+
+    // Phase 2: background cache refresh + SSE broadcast (fire-and-forget)
+    processWebhookEvent('sonarr', eventType).catch(err => {
+      logToFile(`[Webhook] Sonarr background refresh error: ${err.message}`);
+    });
+
+    res.status(200).json({ received: true });
+  } catch (error) {
+    logToFile(`[Webhook] Sonarr error: ${error.message}`);
+    res.status(200).json({ received: true });
+  }
+});
+
+/**
+ * POST /api/webhook/radarr
+ * Receives webhook events from Radarr instances.
+ * Validates the secret, logs the event, refreshes cache, broadcasts SSE, and returns 200.
+ *
+ * Phase 2: integrated with PALDRA cache + SSE for real-time dashboard updates.
+ * Phase 6: rate limiting, input validation, replay protection.
+ */
+router.post('/radarr', webhookLimiter, (req, res) => {
+  if (!validateWebhookSecret(req)) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  const validation = validatePayload(req.body);
+  if (!validation.valid) {
+    logToFile(`[Webhook] Radarr payload rejected: ${validation.reason}`);
+    return res.status(400).json({ error: validation.reason });
+  }
+
+  const { eventType, instanceName, eventDate } = validation;
+
+  if (isReplay(eventType, instanceName, eventDate)) {
+    logToFile(`[Webhook] Radarr duplicate event ignored: ${eventType} @ ${eventDate}`);
+    return res.status(200).json({ received: true, duplicate: true });
+  }
+
+  try {
+    logToFile(`[Webhook] Radarr event received - Type: ${eventType}, Instance: ${instanceName || 'unknown'}`);
+    logToFile(`[Webhook] Radarr payload: ${JSON.stringify(req.body)}`);
+
+    // Phase 5.1: update webhook metrics for polling optimization
+    const radarrInstances = getRadarrInstances();
+    const instance = radarrInstances.find(i => i.name === instanceName);
+    if (instance) {
+      cache.updateWebhookMetrics(instance.url);
+    }
+
+    // Phase 2: background cache refresh + SSE broadcast (fire-and-forget)
+    processWebhookEvent('radarr', eventType).catch(err => {
+      logToFile(`[Webhook] Radarr background refresh error: ${err.message}`);
+    });
+
+    res.status(200).json({ received: true });
+  } catch (error) {
+    logToFile(`[Webhook] Radarr error: ${error.message}`);
+    res.status(200).json({ received: true });
+  }
+});
+
+module.exports = router;

server/utils/cache.js

@@ -72,4 +72,64 @@ class MemoryCache {
 
 const cache = new MemoryCache();
 
+// Webhook metrics for polling optimization
+// These are stored separately from regular cache entries
+const webhookMetrics = {
+  // Per-instance metrics: key = instance URL, value = { lastWebhookTimestamp, eventsReceived, pollsSkipped }
+  instances: new Map(),
+  // Global metrics
+  lastGlobalWebhookTimestamp: null,
+  totalWebhookEventsReceived: 0
+};
+
+function getWebhookMetrics(instanceUrl) {
+  if (!instanceUrl) return null;
+  return webhookMetrics.instances.get(instanceUrl) || {
+    lastWebhookTimestamp: null,
+    eventsReceived: 0,
+    pollsSkipped: 0
+  };
+}
+
+function updateWebhookMetrics(instanceUrl) {
+  const now = Date.now();
+  webhookMetrics.lastGlobalWebhookTimestamp = now;
+  webhookMetrics.totalWebhookEventsReceived++;
+  
+  if (instanceUrl) {
+    const metrics = webhookMetrics.instances.get(instanceUrl) || {
+      lastWebhookTimestamp: null,
+      eventsReceived: 0,
+      pollsSkipped: 0
+    };
+    metrics.lastWebhookTimestamp = now;
+    metrics.eventsReceived++;
+    webhookMetrics.instances.set(instanceUrl, metrics);
+  }
+}
+
+function incrementPollsSkipped(instanceUrl) {
+  if (instanceUrl) {
+    const metrics = webhookMetrics.instances.get(instanceUrl) || {
+      lastWebhookTimestamp: null,
+      eventsReceived: 0,
+      pollsSkipped: 0
+    };
+    metrics.pollsSkipped++;
+    webhookMetrics.instances.set(instanceUrl, metrics);
+  }
+}
+
+function getGlobalWebhookMetrics() {
+  return {
+    lastGlobalWebhookTimestamp: webhookMetrics.lastGlobalWebhookTimestamp,
+    totalWebhookEventsReceived: webhookMetrics.totalWebhookEventsReceived,
+    instances: Object.fromEntries(webhookMetrics.instances)
+  };
+}
+
 module.exports = cache;
+module.exports.getWebhookMetrics = getWebhookMetrics;
+module.exports.updateWebhookMetrics = updateWebhookMetrics;
+module.exports.incrementPollsSkipped = incrementPollsSkipped;
+module.exports.getGlobalWebhookMetrics = getGlobalWebhookMetrics;

server/utils/config.js

@@ -114,6 +114,14 @@ function getRtorrentInstances() {
   );
 }
 
+function getWebhookSecret() {
+  return process.env.SOFARR_WEBHOOK_SECRET || '';
+}
+
+function getSofarrBaseUrl() {
+  return process.env.SOFARR_BASE_URL || '';
+}
+
 module.exports = {
   getSABnzbdInstances,
   getSonarrInstances,
@@ -121,6 +129,8 @@ module.exports = {
   getQbittorrentInstances,
   getTransmissionInstances,
   getRtorrentInstances,
+  getWebhookSecret,
+  getSofarrBaseUrl,
   parseInstances,
   validateInstanceUrl
 };

server/utils/poller.js

@@ -14,6 +14,13 @@ const POLL_INTERVAL = (rawPollInterval === 'off' || rawPollInterval === 'false'
   : (parseInt(process.env.POLL_INTERVAL, 10) || 5000);
 const POLLING_ENABLED = POLL_INTERVAL > 0;
 
+// Webhook fallback timeout in minutes (default 10)
+const WEBHOOK_FALLBACK_TIMEOUT_MINUTES = parseInt(process.env.WEBHOOK_FALLBACK_TIMEOUT, 10) || 10;
+const WEBHOOK_FALLBACK_TIMEOUT_MS = WEBHOOK_FALLBACK_TIMEOUT_MINUTES * 60 * 1000;
+
+// Webhook poll interval multiplier when webhooks are active (default 3x)
+const WEBHOOK_POLL_INTERVAL_MULTIPLIER = parseInt(process.env.WEBHOOK_POLL_INTERVAL_MULTIPLIER, 10) || 3;
+
 let polling = false;
 let lastPollTimings = null;
 
@@ -30,6 +37,42 @@ async function timed(label, fn) {
   return { label, result, ms: Date.now() - t0 };
 }
 
+// Helper function to determine if instance polling should be skipped
+function shouldSkipInstancePolling(instances, instanceType) {
+  if (!instances || instances.length === 0) {
+    return false;
+  }
+
+  const now = Date.now();
+  let allInstancesHaveRecentWebhooks = true;
+  let skippedCount = 0;
+
+  for (const instance of instances) {
+    const metrics = cache.getWebhookMetrics(instance.url);
+    
+    // Skip polling if:
+    // 1. Webhook events have been received (eventsReceived > 0)
+    // 2. Last webhook was recent (within fallback timeout)
+    // 3. Webhook has been enabled (we have metrics)
+    const hasWebhookActivity = metrics && metrics.eventsReceived > 0;
+    const isRecent = metrics && metrics.lastWebhookTimestamp && (now - metrics.lastWebhookTimestamp) < WEBHOOK_FALLBACK_TIMEOUT_MS;
+    
+    if (hasWebhookActivity && isRecent) {
+      skippedCount++;
+      cache.incrementPollsSkipped(instance.url);
+    } else {
+      allInstancesHaveRecentWebhooks = false;
+    }
+  }
+
+  if (allInstancesHaveRecentWebhooks && skippedCount > 0) {
+    console.log(`[Poller] Skipping ${instanceType} polling for ${skippedCount} instance(s) with active webhooks`);
+    return true;
+  }
+
+  return false;
+}
+
 async function pollAllServices() {
   if (polling) {
     console.log('[Poller] Previous poll still running, skipping');
@@ -46,36 +89,50 @@ async function pollAllServices() {
     const sonarrInstances = getSonarrInstances();
     const radarrInstances = getRadarrInstances();
 
+    // Check webhook fallback: if no webhook events for WEBHOOK_FALLBACK_TIMEOUT, force full poll
+    const globalMetrics = cache.getGlobalWebhookMetrics();
+    const now = Date.now();
+    const lastWebhookTime = globalMetrics.lastGlobalWebhookTimestamp;
+    const fallbackTriggered = lastWebhookTime && (now - lastWebhookTime) > WEBHOOK_FALLBACK_TIMEOUT_MS;
+    
+    if (fallbackTriggered) {
+      console.log(`[Poller] Webhook fallback triggered: no webhook events for ${WEBHOOK_FALLBACK_TIMEOUT_MINUTES} minutes, forcing full poll`);
+    }
+
+    // Determine which instances should be polled based on webhook activity
+    const shouldPollSonarr = fallbackTriggered || !shouldSkipInstancePolling(sonarrInstances, 'sonarr');
+    const shouldPollRadarr = fallbackTriggered || !shouldSkipInstancePolling(radarrInstances, 'radarr');
+
     // All fetches in parallel, each individually timed
     const results = await Promise.all([
       timed('Download Clients', async () => {
         const downloadsByType = await getDownloadsByClientType();
         return downloadsByType;
       }),
-      timed('Sonarr Tags', async () => {
+      shouldPollSonarr ? timed('Sonarr Tags', async () => {
         const tagsByType = await arrRetrieverRegistry.getTagsByType();
         return tagsByType.sonarr || [];
-      }),
-      timed('Sonarr Queue', async () => {
+      }) : timed('Sonarr Tags', async () => []),
+      shouldPollSonarr ? timed('Sonarr Queue', async () => {
         const queuesByType = await arrRetrieverRegistry.getQueuesByType();
         return queuesByType.sonarr || [];
-      }),
-      timed('Sonarr History', async () => {
+      }) : timed('Sonarr Queue', async () => []),
+      shouldPollSonarr ? timed('Sonarr History', async () => {
         const historyByType = await arrRetrieverRegistry.getHistoryByType({ pageSize: 10 });
         return historyByType.sonarr || [];
-      }),
-      timed('Radarr Queue', async () => {
+      }) : timed('Sonarr History', async () => []),
+      shouldPollRadarr ? timed('Radarr Queue', async () => {
         const queuesByType = await arrRetrieverRegistry.getQueuesByType();
         return queuesByType.radarr || [];
-      }),
-      timed('Radarr History', async () => {
+      }) : timed('Radarr Queue', async () => []),
+      shouldPollRadarr ? timed('Radarr History', async () => {
         const historyByType = await arrRetrieverRegistry.getHistoryByType({ pageSize: 10 });
         return historyByType.radarr || [];
-      }),
-      timed('Radarr Tags', async () => {
+      }) : timed('Radarr History', async () => []),
+      shouldPollRadarr ? timed('Radarr Tags', async () => {
         const tagsByType = await arrRetrieverRegistry.getTagsByType();
         return tagsByType.radarr || [];
-      }),
+      }) : timed('Radarr Tags', async () => []),
     ]);
 
     const [
@@ -163,43 +220,63 @@ async function pollAllServices() {
     cache.set('poll:qbittorrent', qbittorrentLegacy, cacheTTL);
 
     // Sonarr
-    cache.set('poll:sonarr-tags', sonarrTagsResults, cacheTTL);
-    // Tag queue/history records with _instanceUrl so embedded series/movie objects can build links
-    cache.set('poll:sonarr-queue', {
-      records: sonarrQueues.flatMap(q => {
-        const inst = sonarrInstances.find(i => i.id === q.instance);
-        const url = inst ? inst.url : null;
-        const key = inst ? inst.apiKey : null;
-        return (q.data.records || []).map(r => {
-          if (r.series) r.series._instanceUrl = url;
-          r._instanceUrl = url;
-          r._instanceKey = key;
-          return r;
-        });
-      })
-    }, cacheTTL);
-    cache.set('poll:sonarr-history', {
-      records: sonarrHistories.flatMap(h => h.data.records || [])
-    }, cacheTTL);
+    if (shouldPollSonarr) {
+      cache.set('poll:sonarr-tags', sonarrTagsResults, cacheTTL);
+      // Tag queue/history records with _instanceUrl so embedded series/movie objects can build links
+      cache.set('poll:sonarr-queue', {
+        records: sonarrQueues.flatMap(q => {
+          const inst = sonarrInstances.find(i => i.id === q.instance);
+          const url = inst ? inst.url : null;
+          const key = inst ? inst.apiKey : null;
+          return (q.data.records || []).map(r => {
+            if (r.series) r.series._instanceUrl = url;
+            r._instanceUrl = url;
+            r._instanceKey = key;
+            return r;
+          });
+        })
+      }, cacheTTL);
+      cache.set('poll:sonarr-history', {
+        records: sonarrHistories.flatMap(h => h.data.records || [])
+      }, cacheTTL);
+    } else {
+      // Extend TTL of existing cached data when polling is skipped
+      const existingSonarrTags = cache.get('poll:sonarr-tags');
+      const existingSonarrQueue = cache.get('poll:sonarr-queue');
+      const existingSonarrHistory = cache.get('poll:sonarr-history');
+      if (existingSonarrTags) cache.set('poll:sonarr-tags', existingSonarrTags, cacheTTL);
+      if (existingSonarrQueue) cache.set('poll:sonarr-queue', existingSonarrQueue, cacheTTL);
+      if (existingSonarrHistory) cache.set('poll:sonarr-history', existingSonarrHistory, cacheTTL);
+    }
 
     // Radarr
-    cache.set('poll:radarr-queue', {
-      records: radarrQueues.flatMap(q => {
-        const inst = radarrInstances.find(i => i.id === q.instance);
-        const url = inst ? inst.url : null;
-        const key = inst ? inst.apiKey : null;
-        return (q.data.records || []).map(r => {
-          if (r.movie) r.movie._instanceUrl = url;
-          r._instanceUrl = url;
-          r._instanceKey = key;
-          return r;
-        });
-      })
-    }, cacheTTL);
-    cache.set('poll:radarr-history', {
-      records: radarrHistories.flatMap(h => h.data.records || [])
-    }, cacheTTL);
-    cache.set('poll:radarr-tags', radarrTagsResults.flatMap(t => t.data || []), cacheTTL);
+    if (shouldPollRadarr) {
+      cache.set('poll:radarr-queue', {
+        records: radarrQueues.flatMap(q => {
+          const inst = radarrInstances.find(i => i.id === q.instance);
+          const url = inst ? inst.url : null;
+          const key = inst ? inst.apiKey : null;
+          return (q.data.records || []).map(r => {
+            if (r.movie) r.movie._instanceUrl = url;
+            r._instanceUrl = url;
+            r._instanceKey = key;
+            return r;
+          });
+        })
+      }, cacheTTL);
+      cache.set('poll:radarr-history', {
+        records: radarrHistories.flatMap(h => h.data.records || [])
+      }, cacheTTL);
+      cache.set('poll:radarr-tags', radarrTagsResults.flatMap(t => t.data || []), cacheTTL);
+    } else {
+      // Extend TTL of existing cached data when polling is skipped
+      const existingRadarrQueue = cache.get('poll:radarr-queue');
+      const existingRadarrHistory = cache.get('poll:radarr-history');
+      const existingRadarrTags = cache.get('poll:radarr-tags');
+      if (existingRadarrQueue) cache.set('poll:radarr-queue', existingRadarrQueue, cacheTTL);
+      if (existingRadarrHistory) cache.set('poll:radarr-history', existingRadarrHistory, cacheTTL);
+      if (existingRadarrTags) cache.set('poll:radarr-tags', existingRadarrTags, cacheTTL);
+    }
 
     // qBittorrent (already set above in download clients section)
 

tests/README.md

@@ -41,7 +41,10 @@ tests/
 │   └── tokenStore.test.js     # JSON file token store: store/get/clear, TTL expiry
 └── integration/
     ├── health.test.js         # GET /health and /ready endpoints
-    └── auth.test.js           # Full login/logout/me/csrf flows via supertest + nock
+    ├── auth.test.js           # Full login/logout/me/csrf flows via supertest + nock
+    ├── history.test.js        # GET /api/history/recent: auth, filtering, deduplication
+    └── webhook.test.js        # POST /api/webhook/sonarr+radarr: secret, validation,
+                               #   replay protection, metrics, security assertions
 ```
 
 ## Key design decisions
@@ -60,6 +63,7 @@ The tested files meet these per-file minimums (enforced in CI):
 |---|---|---|
 | `server/app.js` | 85% | 65% |
 | `server/routes/auth.js` | 85% | 70% |
+| `server/routes/webhook.js` | 80% | 70% |
 | `server/middleware/requireAuth.js` | 75% | 80% |
 | `server/utils/sanitizeError.js` | 60% | — |
 | `server/utils/config.js` | 50% | 55% |

tests/integration/webhook.test.js

@@ -0,0 +1,395 @@
+// Copyright (c) 2026 Gordon Bolton. MIT License.
+/**
+ * Integration tests for webhook endpoints:
+ *   POST /api/webhook/sonarr
+ *   POST /api/webhook/radarr
+ *
+ * Uses supertest against createApp() (no real server).
+ * processWebhookEvent() makes outbound *arr API calls — those are blocked by
+ * nock so tests remain hermetic (fire-and-forget, not awaited by the handler).
+ *
+ * Covers:
+ *  - 401 when X-Sofarr-Webhook-Secret is missing or wrong
+ *  - 400 when payload is invalid (missing/unknown eventType, non-object body)
+ *  - 200 + { received: true } for valid events
+ *  - Replay protection: second identical event returns { duplicate: true }
+ *  - Test event (eventType=Test) is accepted and short-circuits the cache refresh
+ *  - cache.updateWebhookMetrics is called when a known instance name is provided
+ *  - cache.getGlobalWebhookMetrics reflects the recorded event
+ */
+
+import request from 'supertest';
+import nock from 'nock';
+import { beforeEach, afterEach } from 'vitest';
+import { createRequire } from 'module';
+import { createApp } from '../../server/app.js';
+
+const require = createRequire(import.meta.url);
+const cache = require('../../server/utils/cache.js');
+
+const VALID_SECRET = 'test-webhook-secret-abc';
+
+// Minimal valid Sonarr Grab payload
+const SONARR_GRAB = {
+  eventType: 'Grab',
+  instanceName: 'Main Sonarr',
+  date: '2026-05-19T10:00:00.000Z',
+  series: { id: 1, title: 'Test Show' },
+  episodes: [{ id: 10, episodeNumber: 1, seasonNumber: 1 }]
+};
+
+// Minimal valid Radarr Grab payload
+const RADARR_GRAB = {
+  eventType: 'Grab',
+  instanceName: 'Main Radarr',
+  date: '2026-05-19T10:00:01.000Z',
+  movie: { id: 1, title: 'Test Movie' }
+};
+
+// Minimal Test event (sent by *arr "Test" button in notifications settings)
+const SONARR_TEST = {
+  eventType: 'Test',
+  instanceName: 'Main Sonarr',
+  date: '2026-05-19T10:00:02.000Z'
+};
+
+function makeApp() {
+  process.env.SOFARR_WEBHOOK_SECRET = VALID_SECRET;
+  process.env.SONARR_INSTANCES = JSON.stringify([
+    { id: 'sonarr-1', name: 'Main Sonarr', url: 'https://sonarr.test', apiKey: 'sk' }
+  ]);
+  process.env.RADARR_INSTANCES = JSON.stringify([
+    { id: 'radarr-1', name: 'Main Radarr', url: 'https://radarr.test', apiKey: 'rk' }
+  ]);
+  return createApp({ skipRateLimits: true });
+}
+
+function postSonarr(app, payload, secret = VALID_SECRET) {
+  const req = request(app).post('/api/webhook/sonarr').send(payload);
+  if (secret !== null) req.set('X-Sofarr-Webhook-Secret', secret);
+  return req;
+}
+
+function postRadarr(app, payload, secret = VALID_SECRET) {
+  const req = request(app).post('/api/webhook/radarr').send(payload);
+  if (secret !== null) req.set('X-Sofarr-Webhook-Secret', secret);
+  return req;
+}
+
+beforeEach(() => {
+  // Block outbound *arr calls made by processWebhookEvent (fire-and-forget)
+  nock('https://sonarr.test').persist().get(/.*/).reply(200, { records: [] });
+  nock('https://radarr.test').persist().get(/.*/).reply(200, { records: [] });
+});
+
+afterEach(() => {
+  nock.cleanAll();
+  delete process.env.SOFARR_WEBHOOK_SECRET;
+});
+
+// ---------------------------------------------------------------------------
+// Secret validation
+// ---------------------------------------------------------------------------
+describe('POST /api/webhook/sonarr — secret validation', () => {
+  it('returns 401 when X-Sofarr-Webhook-Secret header is missing', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, SONARR_GRAB, null);
+    expect(res.status).toBe(401);
+    expect(res.body.error).toBe('Unauthorized');
+  });
+
+  it('returns 401 when X-Sofarr-Webhook-Secret header is wrong', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, SONARR_GRAB, 'wrong-secret');
+    expect(res.status).toBe(401);
+    expect(res.body.error).toBe('Unauthorized');
+  });
+
+  it('returns 401 when SOFARR_WEBHOOK_SECRET is not configured', async () => {
+    delete process.env.SOFARR_WEBHOOK_SECRET;
+    const app = createApp({ skipRateLimits: true });
+    const res = await postSonarr(app, SONARR_GRAB, 'anything');
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('POST /api/webhook/radarr — secret validation', () => {
+  it('returns 401 when X-Sofarr-Webhook-Secret header is missing', async () => {
+    const app = makeApp();
+    const res = await postRadarr(app, RADARR_GRAB, null);
+    expect(res.status).toBe(401);
+    expect(res.body.error).toBe('Unauthorized');
+  });
+
+  it('returns 401 when X-Sofarr-Webhook-Secret header is wrong', async () => {
+    const app = makeApp();
+    const res = await postRadarr(app, RADARR_GRAB, 'bad-secret');
+    expect(res.status).toBe(401);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Input validation
+// ---------------------------------------------------------------------------
+describe('POST /api/webhook/sonarr — input validation', () => {
+  it('returns 400 when body is not a JSON object (array)', async () => {
+    const app = makeApp();
+    const res = await request(app)
+      .post('/api/webhook/sonarr')
+      .set('X-Sofarr-Webhook-Secret', VALID_SECRET)
+      .send([{ eventType: 'Grab' }]);
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 when eventType is missing', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, { instanceName: 'Main Sonarr' });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/eventType/);
+  });
+
+  it('returns 400 when eventType is an unknown value', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, { eventType: 'HackerThing', date: '2026-01-01T00:00:00Z' });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/Unknown eventType/);
+  });
+
+  it('returns 400 when eventType is not a string', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, { eventType: 42 });
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 when eventType exceeds 64 characters', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, { eventType: 'G'.repeat(65) });
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 when instanceName is not a string', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, { eventType: 'Grab', instanceName: 99 });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/instanceName/);
+  });
+});
+
+describe('POST /api/webhook/radarr — input validation', () => {
+  it('returns 400 when eventType is missing', async () => {
+    const app = makeApp();
+    const res = await postRadarr(app, { instanceName: 'Main Radarr' });
+    expect(res.status).toBe(400);
+  });
+
+  it('returns 400 when eventType is unknown', async () => {
+    const app = makeApp();
+    const res = await postRadarr(app, { eventType: 'Injected', date: '2026-01-01T00:00:00Z' });
+    expect(res.status).toBe(400);
+    expect(res.body.error).toMatch(/Unknown eventType/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Happy path — valid events
+// ---------------------------------------------------------------------------
+describe('POST /api/webhook/sonarr — valid events', () => {
+  it('returns 200 { received: true } for a valid Grab event', async () => {
+    const app = makeApp();
+    const payload = { ...SONARR_GRAB, date: '2026-05-19T11:00:00.000Z' };
+    const res = await postSonarr(app, payload);
+    expect(res.status).toBe(200);
+    expect(res.body.received).toBe(true);
+    expect(res.body.duplicate).toBeUndefined();
+  });
+
+  it('returns 200 { received: true } for a Test event', async () => {
+    const app = makeApp();
+    const payload = { ...SONARR_TEST, date: '2026-05-19T11:01:00.000Z' };
+    const res = await postSonarr(app, payload);
+    expect(res.status).toBe(200);
+    expect(res.body.received).toBe(true);
+  });
+
+  it('accepts DownloadFolderImported event', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, {
+      eventType: 'DownloadFolderImported',
+      instanceName: 'Main Sonarr',
+      date: '2026-05-19T11:02:00.000Z'
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.received).toBe(true);
+  });
+
+  it('accepts event without instanceName field', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, {
+      eventType: 'Grab',
+      date: '2026-05-19T11:03:00.000Z'
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.received).toBe(true);
+  });
+});
+
+describe('POST /api/webhook/radarr — valid events', () => {
+  it('returns 200 { received: true } for a valid Grab event', async () => {
+    const app = makeApp();
+    const payload = { ...RADARR_GRAB, date: '2026-05-19T12:00:00.000Z' };
+    const res = await postRadarr(app, payload);
+    expect(res.status).toBe(200);
+    expect(res.body.received).toBe(true);
+  });
+
+  it('accepts Download event', async () => {
+    const app = makeApp();
+    const res = await postRadarr(app, {
+      eventType: 'Download',
+      instanceName: 'Main Radarr',
+      date: '2026-05-19T12:01:00.000Z'
+    });
+    expect(res.status).toBe(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Replay protection
+// ---------------------------------------------------------------------------
+describe('Replay protection', () => {
+  it('sonarr: second identical event (same date) returns duplicate:true', async () => {
+    const app = makeApp();
+    const payload = {
+      eventType: 'Grab',
+      instanceName: 'Main Sonarr',
+      date: '2026-05-19T13:00:00.000Z'
+    };
+    const first = await postSonarr(app, payload);
+    expect(first.status).toBe(200);
+    expect(first.body.duplicate).toBeUndefined();
+
+    const second = await postSonarr(app, payload);
+    expect(second.status).toBe(200);
+    expect(second.body.duplicate).toBe(true);
+  });
+
+  it('sonarr: event with different date is not considered a duplicate', async () => {
+    const app = makeApp();
+    const first = await postSonarr(app, {
+      eventType: 'Grab', instanceName: 'Main Sonarr', date: '2026-05-19T14:00:00.000Z'
+    });
+    expect(first.body.duplicate).toBeUndefined();
+
+    const second = await postSonarr(app, {
+      eventType: 'Grab', instanceName: 'Main Sonarr', date: '2026-05-19T14:01:00.000Z'
+    });
+    expect(second.body.duplicate).toBeUndefined();
+  });
+
+  it('radarr: second identical event returns duplicate:true', async () => {
+    const app = makeApp();
+    const payload = {
+      eventType: 'Download',
+      instanceName: 'Main Radarr',
+      date: '2026-05-19T15:00:00.000Z'
+    };
+    await postRadarr(app, payload);
+    const second = await postRadarr(app, payload);
+    expect(second.body.duplicate).toBe(true);
+  });
+
+  it('event without date field is never considered a duplicate', async () => {
+    const app = makeApp();
+    const payload = { eventType: 'Grab', instanceName: 'Main Sonarr' };
+    const first = await postSonarr(app, payload);
+    const second = await postSonarr(app, payload);
+    // Neither should be flagged as duplicate (no date = no replay key)
+    expect(first.body.duplicate).toBeUndefined();
+    expect(second.body.duplicate).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Webhook metrics (Phase 5.1 integration)
+// ---------------------------------------------------------------------------
+describe('Webhook metrics — cache.updateWebhookMetrics integration', () => {
+  it('sonarr: increments eventsReceived for a known instance', async () => {
+    const app = makeApp();
+    const instanceUrl = 'https://sonarr.test';
+    const before = cache.getWebhookMetrics(instanceUrl);
+    const countBefore = before ? before.eventsReceived : 0;
+
+    await postSonarr(app, {
+      eventType: 'Grab',
+      instanceName: 'Main Sonarr',
+      date: '2026-05-19T16:00:00.000Z'
+    });
+
+    const after = cache.getWebhookMetrics(instanceUrl);
+    expect(after.eventsReceived).toBe(countBefore + 1);
+    expect(after.lastWebhookTimestamp).toBeGreaterThan(0);
+  });
+
+  it('radarr: increments eventsReceived for a known instance', async () => {
+    const app = makeApp();
+    const instanceUrl = 'https://radarr.test';
+    const before = cache.getWebhookMetrics(instanceUrl);
+    const countBefore = before ? before.eventsReceived : 0;
+
+    await postRadarr(app, {
+      eventType: 'Download',
+      instanceName: 'Main Radarr',
+      date: '2026-05-19T16:01:00.000Z'
+    });
+
+    const after = cache.getWebhookMetrics(instanceUrl);
+    expect(after.eventsReceived).toBe(countBefore + 1);
+  });
+
+  it('does not crash when instanceName does not match a configured instance', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, {
+      eventType: 'Grab',
+      instanceName: 'Unknown Instance',
+      date: '2026-05-19T16:02:00.000Z'
+    });
+    expect(res.status).toBe(200);
+    expect(res.body.received).toBe(true);
+  });
+
+  it('global metrics totalWebhookEventsReceived increments after valid event', async () => {
+    const app = makeApp();
+    const beforeGlobal = cache.getGlobalWebhookMetrics();
+    const beforeCount = beforeGlobal.totalWebhookEventsReceived;
+
+    await postSonarr(app, {
+      eventType: 'Grab',
+      instanceName: 'Main Sonarr',
+      date: '2026-05-19T17:00:00.000Z'
+    });
+
+    const afterGlobal = cache.getGlobalWebhookMetrics();
+    expect(afterGlobal.totalWebhookEventsReceived).toBe(beforeCount + 1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Secret not included in response
+// ---------------------------------------------------------------------------
+describe('Security — secret never leaks', () => {
+  it('sonarr: SOFARR_WEBHOOK_SECRET is not present in any response body', async () => {
+    const app = makeApp();
+    const res = await postSonarr(app, {
+      eventType: 'Grab',
+      instanceName: 'Main Sonarr',
+      date: '2026-05-19T18:00:00.000Z'
+    });
+    expect(JSON.stringify(res.body)).not.toContain(VALID_SECRET);
+  });
+
+  it('radarr: SOFARR_WEBHOOK_SECRET is not present in 401 response body', async () => {
+    const app = makeApp();
+    const res = await postRadarr(app, RADARR_GRAB, 'wrong');
+    expect(JSON.stringify(res.body)).not.toContain(VALID_SECRET);
+  });
+});