Skip to content

Webhooks

chodeus edited this page Oct 22, 2026 · 12 revisions

🏠 Home › Webhooks

Webhooks

One inbound webhook lets Sonarr, Radarr or Tautulli trigger a poster job the moment a new item lands.

On this page

The endpoint

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.

Authentication

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.

Accepted event types

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

Wiring your *arr / Tautulli

Auto-setup (Radarr / Sonarr)

Settings → Webhooks → Auto-setup adds CHUB's webhook to each Radarr and Sonarr through their API.

  1. 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.
  2. 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).
  3. 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.

Sonarr / Radarr by hand

  1. Settings → Connect → + → Webhook.

  2. URL: copy from CHUB's Settings → Webhooks page.

  3. Method: POST.

  4. 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.

  5. Headers: if a secret is set, add X-Webhook-Secret: <your secret> (use Reveal to copy the value).

  6. Click Test (CHUB returns 200; it appears under Recent callers), then Save.

Tautulli

Also catches items added on the Plex side that the *arrs never see.

  1. Settings → Notification Agents → Add a new notification agent → Webhook.
  2. 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).
  3. Triggers: Recently Added is usually enough.
  4. Data format: JSON. Leave the template blank.

Which instance sent it

CHUB works out which instance sent each webhook:

  1. ?instance=<name> in the URL (or an X-Chub-Instance: <name> header) names the instance outright. Auto-setup always adds it. Use the exact instance name from Settings → Instances.
  2. Otherwise, by the caller's IP. A Docker service name like sonarr is 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).
  3. Behind a reverse proxy (Traefik/nginx/Caddy) the caller's IP is the proxy's. CHUB honors X-Forwarded-For from any proxy listed in general.trusted_proxies (default private = 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=.

Plex availability retry

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.

Force re-uploads per instance

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-push

Scheduled and manual runs still skip unchanged posters.

Recent callers

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.

Troubleshooting

  • 401 Unauthorized — webhook_secret is 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.
  • 200 but nothing happens — the event isn't on the allow-list (e.g. On Grab), the same item fired within the 600s dedup window (look for Duplicate webhook debounced at debug level), poster_renamerr is 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_retries or wait for the next scheduled rename.

See Troubleshooting for more.

Additional HTTP triggers

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

Clone this wiki locally