enhancement(webhook): document overrides and uses

ShanaryS · ShanaryS · commit 18a4322325a6 · 2025-01-19T21:37:48.000-05:00
diff --git a/docs/basics/options.md b/docs/basics/options.md
@@ -750,11 +750,12 @@ skipRecheck: false,
 | ----------------------- | -------------- | --------------------------- | --------- | ------- |
 | `includeSingleEpisodes` | `N/A`          | `--include-single-episodes` | `boolean` | `false` |
 
-:::warning NOTICE
+:::tip
 
-Behavior of this option has changed in v6, please see the
-[migration guide](../v6-migration.md#updated-includesingleepisodes-behavior) for
-details on the implementation's changes'.
+It's recommended to use `includeSingleEpisodes: false` in your config and override it for webhook
+commands triggered on [download completion](../tutorials/triggering-searches.md#setting-up-your-torrent-client).
+Combined with matching single episodes from announce, this should match all episodes without
+the downside of searching for [trumped/dead torrents](../v6-migration.md#updated-includesingleepisodes-behavior).
 
 :::
 
@@ -766,13 +767,9 @@ ignored by default).
 This will **NOT** include episodes present inside season packs (data-based
 searches).
 
-:::
-
-:::tip
-
-This option has explicit usage examples given in the
-[config templates](https://github.com/cross-seed/cross-seed/blob/master/src/config.template.cjs#L261-L275)
-which outlines the most common scenarios.
+Behavior of this option has changed in v6, please see the
+[migration guide](../v6-migration.md#updated-includesingleepisodes-behavior) for
+details on the implementation's changes'.
 
 :::
 
@@ -1177,16 +1174,16 @@ Content-Type: application/json
     "trackers": ["string"],
     "source": "announce | inject | rss | search | webhook",
     "result": "SAVED | INJECTED | FAILURE",
-	"paused": false,
-	"decisions": ["string"],
-	"searchee": {
-		"category": "string",
-		"tags": ["string"],
-		"trackers": ["string"],
-		"length": 123,
-		"infoHash": "string",
-		"path": "string",
-		"source": "torrentClient | torrentFile | dataDir | virtual",
+    "paused": false,
+    "decisions": ["string"],
+    "searchee": {
+        "category": "string",
+        "tags": ["string"],
+        "trackers": ["string"],
+        "length": 123,
+        "infoHash": "string",
+        "path": "string",
+        "source": "torrentClient | torrentFile | dataDir | virtual"
 	}
   }
 }
diff --git a/docs/reference/api.md b/docs/reference/api.md
@@ -56,13 +56,21 @@ POST /api/webhook
 	// infoHash or path is required but not both (infoHash is recommended)
 	infoHash: "<infoHash of torrent>",
 	path: "/path/to/torrent/file.mkv",
+	// All of the following are optional with their defaults shown
+	ignoreCrossSeeds: true,
+	ignoreExcludeRecentSearch: false,
+	ignoreExcludeOlder: false,
+	ignoreBlockList: false,
+	includeSingleEpisodes: false,
+	includeNonVideos: false,
 }
 ```
 
 ```shell script
 curl -XPOST http://localhost:2468/api/webhook \
   --data-urlencode 'infoHash=<torrent infoHash here>' \
-  --data-urlencode 'path=/path/to/torrent/file.mkv'
+  --data-urlencode 'path=/path/to/torrent/file.mkv' \
+  --data-urlencode 'includeSingleEpisodes=true'
 ```
 
 Alternatively, you can use JSON:
diff --git a/docs/tutorials/triggering-searches.md b/docs/tutorials/triggering-searches.md
@@ -62,14 +62,42 @@ We will refer to this as `<BASE_URL>` below.
 
 ### Setting Up Your Torrent Client
 
+There are likely two versions of webhook command you want to use, depending
+if you want to include episodes or not. There are other options available to
+customize found [`here`](../reference/api.md#request-payload), but these offer
+no benefit to download completion.
+
+:::warning
+
+You may be tempted to set `ignoreCrossSeeds: false` for download completion triggers
+but this offers no benefits. Partial matches will trigger a completion event in your
+client once it completes. This creates a _useless_ webhook search since this media
+was just processed by cross-seed.
+
+:::
+
+:::tip
+
+Use the webhook command with `-d "includeSingleEpisodes=true"` with `includeSingleEpisodes: false`
+in your config to minimize useless searches.
+
+[**Read more**](../v6-migration.md#updated-includesingleepisodes-behavior)
+
+:::
+
 <details>
 <summary><strong>rTorrent</strong></summary>
 
 1. Create a script named `rtorrent-cross-seed.sh`, replacing `<BASE_URL>` and
    `<API_KEY>` with the correct values from above:
     ```shell
     #!/bin/sh
-    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> --data-urlencode "infoHash=$2"
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=$2" -d "includeSingleEpisodes=true"
+    ```
+    OR
+    ```shell
+    #!/bin/sh
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=$2"
     ```
 2. Make it executable:
     ```shell
@@ -91,7 +119,11 @@ We will refer to this as `<BASE_URL>` below.
 2. Enable **Run external program on torrent completion**, replacing `<BASE_URL>`
    and `<API_KEY>` with the correct values from above:
     ```shell
-    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> --data-urlencode "infoHash=%I"
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=%I" -d "includeSingleEpisodes=true"
+    ```
+    OR
+    ```shell
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=%I"
     ```
 
 </details>
@@ -103,7 +135,12 @@ We will refer to this as `<BASE_URL>` below.
    with the correct values from above:
     ```shell
     #!/bin/sh
-    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> --data-urlencode "infoHash=$TR_TORRENT_HASH"
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=$TR_TORRENT_HASH" -d "includeSingleEpisodes=true"
+    ```
+    OR
+    ```shell
+    #!/bin/sh
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=$TR_TORRENT_HASH"
     ```
 2. Make it executable:
     ```shell
@@ -119,13 +156,20 @@ We will refer to this as `<BASE_URL>` below.
 
 1. Create a file called `deluge-cross-seed.sh`, replacing `<BASE_URL>` and
    `<API_KEY>` with the correct values from above:
-
     ```shell
     #!/bin/bash
     infoHash=$1
     name=$2
     path=$3
-    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> --data-urlencode "infoHash=$infoHash"
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=$infoHash" -d "includeSingleEpisodes=true"
+    ```
+    OR
+    ```shell
+    #!/bin/bash
+    infoHash=$1
+    name=$2
+    path=$3
+    curl -XPOST <BASE_URL>/api/webhook?apikey=<API_KEY> -d "infoHash=$infoHash"
     ```
 
 2. Make the script executable:
diff --git a/docs/v6-migration.md b/docs/v6-migration.md
@@ -194,6 +194,15 @@ usually have trumped in favor of season packs. If you're currently using
 `includeSingleEpisodes: true`, please consider switching to `false` if it now
 meets your needs as it will reduce unecessary load on trackers.
 
+:::tip
+
+You can override this option for webhook searches which gives the best of
+both worlds.
+
+[**Read more**](./tutorials/triggering-searches.md#setting-up-your-torrent-client)
+
+:::
+
 ## New Features and Improvements
 
 ### Linking for torrent-based Matches
