One self-hosted app for your shows, movies and music.
title: Alerts description: Send Discord, email, Telegram, ntfy, Gotify, Pushover or webhook messages when a request waits, a download finishes, a title lands in the Library or a health check breaks. level: Setup sidebar: { order: 5 }
An Alert sends a message when something happens: a request waits, a download finishes, a movie lands, a health check breaks. It goes to Discord, email, Telegram, ntfy, Gotify, Pushover or your own webhook. You need the Change settings permission.
Add an Alert
- Open Settings > Alerts and select Add an Alert.
- Give it a Name and pick a Kind: Discord, email, Telegram, ntfy, Gotify, Pushover or Webhook (JSON).
- Fill in the kind's fields (see Kinds).
- Under When to send, untick the moments you do not want. All start ticked; All of these and None of these work on a whole group.
- Leave Send messages on and select Save.
- Select Send a test on the card. You should see the message arrive and the card show Last sent.
Kinds
Discord
In Discord, open the channel settings, then Integrations > Webhooks, and copy the link. Paste it into Discord link; it starts with https://discord.com/. People who added their Discord user ID to their account are mentioned in messages about their requests.
| Field | What to enter |
|---|---|
| Mail server, Port | Your mail server |
| Security | STARTTLS (port 587), TLS (port 465) or None. None only for a mail server on your own network |
| From address | The sender address |
| Mail username, Mail password | The mail account |
| Staff addresses | One or more, split by commas |
Messages about a request go to the people who asked, at their account address. Everything else goes to the staff addresses.
Telegram, ntfy, Gotify and Pushover
| Kind | Fields |
|---|---|
| Telegram | Bot token from @BotFather, Chat ID (user, group or channel ID, or @channel). Message the bot or add it to the group first |
| ntfy | Server address (empty means ntfy.sh), Topic, optional Access token. Anyone who knows the topic can read it |
| Gotify | Server address, App token |
| Pushover | User key (group keys work), App token |
These four get the same short message as Discord: a title line and the details below it.
Webhook
Paste your receiver's address into Webhook link. Each message is one JSON POST; see What a webhook receives. An optional Secret either signs each message or is sent as a bearer token (What the secret does). Use it to run your own steps when a download finishes or files land in the Library, for example copying a finished show to another folder.
Choices
When to send
| Moment | Goes to | When |
|---|---|---|
| New request | Staff | A movie, show or artist waits for approval |
| Approved | Requesters | Their request was approved |
| Declined | Requesters | Declined, with your note |
| Ready | Requesters | Files are in the Library |
| New episodes | Requesters and followers | At most 1 per show per hour. Each person can turn these off |
| New albums | Artist followers | At most 1 per artist per hour |
| Problem reported | Staff | Someone reported a title. Reports are at /requests/reports |
| Problem fixed | Reporter | With your reply |
| Sent to download | Staff | A release went to a downloader |
| Downloaded | Staff | The downloader finished a download. The import comes next |
| Download failed | Staff | A download failed and its release was turned down |
| In the Library | Staff | Files were placed, including a better copy |
| Renamed | Staff | Files got new names |
| Added | Staff | A title was added by hand, from a list or from a request |
| Deleted | Staff | A movie, show, season or episodes left the Library |
| Health | Staff | A health check broke or is fixed |
| Needs a decision | Staff | A download or import needs you |
Season packs
Below the list, Season packs decides what one download with many episodes sends: One Alert for the pack, with a line per episode, or One Alert per episode.
Reach the local network
Off by default. While off, Discord Alerts go only to discord.com and other kinds only to internet servers; links to this machine or your home network are refused, even after a name lookup. Turn it on for a mail server or receiver at home. Redirects are never followed.
Pause an Alert
Untick Send messages. The card shows Off and the Alert stays.
Passwords and tokens
Stored encrypted, then shown as Stored. Leave the field empty to keep it. Point an Alert at another server and you type the secret again; a stored secret never goes to a new place.
If it does not work
Symptom:
Paste the Discord link
Cause: the link does not start with https://discord.com/.
Fix: copy the webhook link again. For a Discord-like server at home, turn on Reach the local network.
Symptom:
Points to the local network, which this Alert may not reach
Cause: the server is on this machine or your home network. Fix: turn on Reach the local network.
Symptom: Last try failed with an answer of 401 or 404. Cause: the link or token is wrong. These are not retried. Fix: correct it and select Send a test.
Symptom: the person who asked got nothing. Cause: no email address or Discord user ID on their account, the moment is unticked, or they turned off new episodes. Fix: check those three.
For experts
Retries
A timeout, a slow-down answer or a server error is retried after 5 s, 30 s and 2 min. A longer wait asked by the server is honoured, up to 5 min. A refusal, such as a wrong link, is not retried. Each failure adds an "Alert could not be sent" row to History.
What a webhook receives
One POST per message, Content-Type: application/json, with these headers:
| Header | Value |
|---|---|
X-HolyArrs-Event |
The moment, such as downloaded, import, download_failed or test |
X-HolyArrs-Delivery |
Random ID for this message |
X-HolyArrs-Timestamp |
With Signs each message: seconds since 1970 |
X-HolyArrs-Signature |
With Signs each message: sha256= plus hex HMAC-SHA256 of <timestamp>.<delivery>.<body>, keyed with your secret |
Authorization |
With Is sent as a bearer token: Bearer <secret> |
With Nothing, no secret is sent. When signing, refuse old timestamps and delivery IDs you have seen, so a copied message cannot be replayed.
A finished download:
{
"moment": "downloaded",
"event_kind": "download_finished",
"subject": "Downloaded: Arrival (2016)",
"text": "Download 3f2a9c1b: finished\nrelease: Arrival.2016.1080p.WEB\ndownloader: qBittorrent\nsave_path: Arrival.2016.1080p.WEB",
"at": "2025-01-01T17:58:40Z",
"movie": { "id": 12, "name": "Arrival", "year": 2016, "tmdb": "329865", "imdb": "tt2543164" },
"data": { "state": "finished", "progress": 1, "release": "Arrival.2016.1080p.WEB", "release_id": 7, "downloader": "qBittorrent", "save_path": "Arrival.2016.1080p.WEB" }
}
The import that follows:
{
"moment": "import",
"event_kind": "import_done",
"subject": "In the Library: Arrival (2016)",
"text": "Import done: 1 placed by hardlink\nfrom: Arrival.2016.1080p.WEB",
"at": "2025-01-01T18:04:11Z",
"movie": { "id": 12, "name": "Arrival", "year": 2016, "tmdb": "329865", "imdb": "tt2543164" },
"data": { "from": "Arrival.2016.1080p.WEB", "paths": [{ "from": "Arrival.2016.1080p.WEB.mkv", "to": "Arrival (2016).mkv", "method": "hardlink" }] }
}
| Moment | event_kind |
|---|---|
grab |
download_sent |
downloaded |
download_finished |
download_failed |
download_failed |
import |
import_done or import_partly_done |
Other fields appear when they apply: test, show and episodes, artist and tracks, report, people. people holds requester names, never addresses. data holds the reasons and paths from the History row behind the message. A full path on this machine (a download folder, a Library folder) is cut to its last name. Any 2xx answer counts as delivered.