Repository navigation
Webhooks
🏠 Home › Webhooks
One inbound webhook lets Sonarr, Radarr or Tautulli trigger a poster job the moment a new item lands.
- The endpoint
- Authentication
- Accepted event types
- Wiring your *arr / Tautulli
- Which instance sent it
- Plex availability retry
- Force re-uploads per instance
- Recent callers
- Troubleshooting
- Additional HTTP triggers
POST http://<chub-host>:8000/api/webhooks/poster/add
Settings → Webhooks shows it with a copy button.
Each call queues a poster job for that one item, running the same steps as poster_renamerr: rename → border (if enabled) → apply by its apply_method. Repeats of the same item, event, instance and season within 600 seconds are dropped (this survives restarts).
Sonarr sends one webhook per episode; episodes from one season collapse into one job that checks only that season's posters. Lidarr isn't supported.
Auth is optional and off by default. Set general.webhook_secret (in config.yml or Settings → General) to require it on every inbound request:
| Method | How | Use for |
|---|---|---|
| Header | X-Webhook-Secret: <secret> |
Sonarr, Radarr (manual setup) |
| Query param | ?secret=<secret> |
Tautulli, auto-setup, and anything that can't send headers |
A wrong or missing secret returns 401. With no secret the endpoint is open — fine on a trusted LAN, and the Webhooks page warns about it. The page has copy buttons for the header, the ?secret= URL and the plain URL.
Only new items and files are processed; anything else gets a 200 and is dropped.
| Event | Sonarr trigger | Radarr trigger | Processed? |
|---|---|---|---|
Download |
On File Import / On File Upgrade / On Import Complete | On File Import / On File Upgrade | ✅ |
SeriesAdd |
On Series Add | — | ✅ |
MovieAdded |
— | On Movie Added | ✅ |
Test |
(Test button) | (Test button) | ✅ acked, no job |
Grab |
On Grab | On Grab | 🚫 file not on disk yet |
Rename |
On Rename | On Rename | 🚫 ignored |
*FileDelete, *Delete, HealthIssue, ApplicationUpdate, … |
— | — | 🚫 ignored |
Settings → Webhooks → Auto-setup adds CHUB's webhook to each Radarr and Sonarr through their API.
- Check CHUB base URL (as your *arrs reach it). It must be reachable *from the arr containers — behind a reverse proxy that's usually a LAN IP or Docker service name, not the public hostname. It's filled in from *CHUB base URL for arr webhooks on Settings → General (
general.public_url) if set, else from an existing CHUB webhook in your *arrs, else from your browser address. - Click Set up webhooks. Each *arr gets a webhook with
?instance=<name>(and?secret=if you set one) in its URL. Only On File Import is turned on; tick Also trigger on file upgrade to add On File Upgrade (usually unnecessary). - The card shows each instance's state. Fix all repairs any whose webhook has drifted from what CHUB would write. A webhook you made yourself under a different name is never touched.
-
Settings → Connect → + → Webhook.
-
URL: copy from CHUB's Settings → Webhooks page.
-
Method:
POST. -
Notification Triggers: check On File Import and On File Upgrade, plus:
- Sonarr → also On Series Add (On Import Complete also works — CHUB de-duplicates it).
- Radarr → also On Movie Added.
Leave the rest unchecked — CHUB ignores them.
-
Headers: if a secret is set, add
X-Webhook-Secret: <your secret>(use Reveal to copy the value). -
Click Test (CHUB returns
200; it appears under Recent callers), then Save.
Also catches items added on the Plex side that the *arrs never see.
- Settings → Notification Agents → Add a new notification agent → Webhook.
-
URL: Tautulli has no Headers field — use the
?secret=URL form from CHUB's Webhooks page (or the plain URL if no secret is set). - Triggers: Recently Added is usually enough.
- Data format: JSON. Leave the template blank.
CHUB works out which instance sent each webhook:
-
?instance=<name>in the URL (or anX-Chub-Instance: <name>header) names the instance outright. Auto-setup always adds it. Use the exact instance name from Settings → Instances. - Otherwise, by the caller's IP. A Docker service name like
sonarris resolved automatically. Two instances on the same IP but different ports are told apart by the payload's instance name, so give each Sonarr/Radarr a distinct Instance Name (*arr Settings → General). -
Behind a reverse proxy (Traefik/nginx/Caddy) the caller's IP is the proxy's. CHUB honors
X-Forwarded-Forfrom any proxy listed ingeneral.trusted_proxies(defaultprivate= any LAN / loopback / Docker address); a forged header from an untrusted caller is ignored.
If CHUB still can't tell instances apart (host networking, identical names, or an untrusted proxy), use ?instance=.
A webhook usually arrives before Plex has scanned the new file, so CHUB waits for the item (or, for Sonarr, that season) to appear. The defaults allow about 5.5 minutes.
general:
webhook_initial_delay: 30 # seconds before the first Plex check (0–3600)
webhook_retry_delay: 30 # seconds between checks (1–3600)
webhook_max_retries: 10 # max retries (0–100)If the budget runs out, the upload is skipped and the next scheduled poster_renamerr picks it up.
CHUB skips uploading a poster that hasn't changed. To make every webhook from an instance re-push (e.g. after wiping a Plex library), turn on Force re-upload on webhook for it on Settings → Instances, or set webhook_force_reupload: true:
instances:
sonarr:
main:
url: http://sonarr:8989
api: ...
webhook_force_reupload: true # webhooks from this Sonarr always re-pushScheduled and manual runs still skip unchanged posters.
Settings → Webhooks lists the last 7 days of calls by host and endpoint, with counts and status — handy to confirm a newly wired *arr is reaching CHUB.
-
401 Unauthorized—webhook_secretis set but the caller isn't sending the header or?secret=. Copy a pre-applied URL/header from Settings → Webhooks, or re-run auto-setup after changing the secret. -
404 Not Found— path typo. It's/api/webhooks/poster/add. -
200but nothing happens — the event isn't on the allow-list (e.g. On Grab), the same item fired within the 600s dedup window (look forDuplicate webhook debouncedat debug level),poster_renamerris switched off (the job says Skipped — poster_renamerr is disabled), or the job ran but failed downstream (check Settings → Jobs). -
Poster went to the wrong library / instance — see Which instance sent it; add
?instance=<name>to the URL. -
Sonarr "Test connection failed" — network issue; Sonarr can't reach CHUB. Verify from inside its container:
curl -sS http://chub:8000/api/health. -
Download didn't get its poster — the Plex availability budget ran out before Plex finished scanning. Bump
webhook_max_retriesor wait for the next scheduled rename.
See Troubleshooting for more.
Endpoints for external automation (cron, Home Assistant, a phone shortcut). All /api/webhooks/* routes are rate-limited. Auth is either the webhook secret or a logged-in session (Authorization: Bearer <token>; not needed when the login is off).
| Method | Endpoint | Auth | What it does |
|---|---|---|---|
POST |
/api/webhooks/unmatched/process |
secret | Enqueue an unmatched_assets run. |
GET |
/api/webhooks/unmatched/status |
session | Return the current unmatched-assets summary. |
GET |
/api/webhooks/wiring |
session | Return the poster/add path + optional secret (used by CHUB's UI to build URLs). |
GET |
/api/webhooks/provision/status |
session | Each *arr's auto-setup state (never the secret URL). |
POST |
/api/webhooks/provision |
session | Add or repair CHUB's webhook in the named *arrs (or all). |
POST |
/api/webhooks/provision/remove |
session | Remove CHUB's webhook from the named *arrs. |
GET |
/api/jobs/webhook-origins?days=7 |
session | Summarize recent webhook calls by client_host + endpoint. |
Next: Troubleshooting · Related: Configuration, Modules