documented MalwareBlocker webhook triggering

docs/docs/configuration/malware-blocker/index.mdx

@@ -34,6 +34,21 @@ When enabled, the Malware Blocker will run according to the configured schedule
 
 </ConfigSection>
 
+<ConfigSection
+  title="Trigger Mode"
+>
+
+Controls how the Malware Blocker is started:
+- **Schedule**: Runs on the configured cron schedule (default).
+- **Webhook**: Runs only when a Sonarr/Radarr "On Grab" webhook is received, scanning just the grabbed download.
+- **Schedule + Webhook**: Both — webhooks scan new grabs immediately, while the schedule remains a safety net.
+
+<Note>
+Webhook triggering is only supported for **Sonarr** and **Radarr**. See [Webhook triggering](./webhook-triggers) for setup.
+</Note>
+
+</ConfigSection>
+
 <ConfigSection
   title="Scheduling Mode"
 >

docs/docs/configuration/malware-blocker/webhook-triggers.mdx

@@ -0,0 +1,84 @@
+---
+sidebar_position: 1
+---
+
+import {
+  ConfigSection,
+  Note,
+  Important,
+  Warning,
+  ElementNavigator,
+  styles
+} from '@site/src/components/documentation';
+
+# Webhook Triggering
+
+By default the Malware Blocker runs on a fixed schedule, which leaves a gap between when a download is
+grabbed and when its files are evaluated. Sonarr and Radarr can call Cleanuparr the moment a release is
+sent to the download client via their **"On Grab"** webhook, so the grabbed download is scanned right
+away instead of waiting for the next scheduled run.
+
+<ElementNavigator />
+
+<div className={styles.documentationPage}>
+
+<Important>
+Webhook triggering is only supported for **Sonarr** and **Radarr**. Set the Malware Blocker
+**Trigger Mode** to **Webhook** or **Schedule + Webhook** for incoming webhooks to be acted on.
+</Important>
+
+<div className={styles.section}>
+
+<ConfigSection
+  title="How it works"
+>
+
+When an "On Grab" webhook arrives, Cleanuparr runs a targeted Malware Blocker scan of just that one
+download (identified by its torrent hash from the webhook), rather than iterating the whole queue. The
+scan runs immediately and is retried a couple of times shortly after, because a torrent often has no
+file metadata yet at grab time.
+
+<Note>
+Because the grabbed torrent may not have downloaded its file list yet, the very first scan can find
+nothing to act on. Keeping the schedule enabled (**Schedule + Webhook**) ensures these are still caught
+by the regular run.
+</Note>
+
+</ConfigSection>
+
+<ConfigSection
+  title="Finding the webhook URL"
+>
+
+Each Sonarr/Radarr instance has its own webhook URL. Open the instance under its connection page
+(**Sonarr** / **Radarr** settings) and use the **Webhook URL** button on the instance to reveal and copy
+it. The URL has the form:
+
+```
+http://<cleanuparr-host>:11011/api/webhooks/malware-blocker/<instanceId>?apikey=<your-api-key>
+```
+
+It already contains your account API key, so it authenticates automatically.
+
+<Warning>
+The URL embeds your API key — treat it as a secret.
+</Warning>
+
+</ConfigSection>
+
+<ConfigSection
+  title="Configuring Sonarr / Radarr"
+>
+
+1. In Sonarr/Radarr, go to **Settings → Connect → + → Webhook**.
+2. Enable the **On Grab** notification trigger.
+3. Set **URL** to the webhook URL copied from Cleanuparr and **Method** to `POST`.
+4. Click **Test** — Cleanuparr acknowledges the test without running a scan — then **Save**.
+
+From now on, every grab is scanned by the Malware Blocker as soon as it reaches the download client.
+
+</ConfigSection>
+
+</div>
+
+</div>