Discord notifications (admin)

GET    /api/admin/discord-notifications       # { enabled, include_auto_approved, has_webhook, recent, error? }; never returns the URL
PUT    /api/admin/discord-notifications       # { enabled, include_auto_approved?, webhook_url? }; blank/omitted URL preserves the saved secret
DELETE /api/admin/discord-notifications       # remove the webhook and disable delivery
POST   /api/admin/discord-notifications/test  # { webhook_url? }; test the draft or stored destination without enabling/saving

Requires credentials:manage. Test is limited to three calls per minute and sends a fixed sample, with no real requester or title. Its result has status and detail; HTTP 200 reports the test outcome, not necessarily successful delivery. Recent delivery rows include request_id, status, detail, attempts, Unix-second updated_at, and optional next_attempt_at; the latest 20 are shown. Statuses are pending, sending, sent, failed, unconfirmed, and cancelled.

This integration is off by default and independent of native push. One incoming webhook receives new saved movie, TV, book, and music requests needing approval, including submissions through MCP. include_auto_approved adds requests accepted without review and defaults off; omitting it on an update preserves its saved value. Alerts contain the title, type, Cantinarr username, approval state at submission, and book formats where applicable. Everyone with channel access can see those fields. A configured External Address adds a link to /approvals for pending requests or the server home otherwise; no address is inferred from incoming headers, arr callback configuration, or MCP settings. Approvals, declines, availability changes, shared-book subscriptions, and retries of existing work do not generate another submission alert. Both book formats in one new request produce one alert. A new scope, requester (except subscriptions to an existing shared book request), library, or revived movie/TV monitoring remains distinct.

The entire discord_notifications settings value is AES-GCM encrypted. URLs must be Discord HTTPS incoming webhook URLs; redirects, arbitrary hosts, and query parameters are rejected. Only ordinary text channels are supported; forum/thread destinations require options this integration does not send. Requests use httpx.External(), wait=true, a ten-second timeout, and disabled mentions. Webhook URL/token values are never returned or logged.

A durable SQLite queue isolates Discord from media-request outcomes. A unique request receipt prevents replay across restarts. Confirmed rate-limit rejections respect the destination-wide retry delay, with at most five attempts within 24 hours. Disconnects, timeouts, unexpected successful responses without a message ID, server errors, and interrupted in-flight attempts are unconfirmed, not automatically reposted: Discord may already have saved the message. Other rejections fail visibly. Disabling or replacing the webhook cancels unsent alerts. Turning off include_auto_approved cancels only unsent automatically approved alerts. Enabling either option does not replay historical requests. Queue-write failures are logged without credentials and reported in Settings; they never roll back an accepted media request.

View the maintained source for this page.