Notifications
Narratorr can send notifications when key events occur in the download and import lifecycle. Each notifier subscribes to one or more events and fires independently — notifications never block the main workflow.
Configure notifications in Settings > Notifications.
Events
Section titled “Events”| Event | Fires When |
|---|---|
| On Grab | A release is sent to a download client |
| On Download Complete | A download client reports a download finished |
| On Import | An audiobook is successfully imported into the library |
| On Failure | A download or import fails |
| On Health Issue | A health check transitions state (e.g. healthy → warning/error) |
Notifier Types
Section titled “Notifier Types”Webhook
Section titled “Webhook”Sends an HTTP request to any URL when an event fires.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| URL | The endpoint to call |
| Method | POST or PUT |
| Headers (JSON) | Optional custom headers as a JSON object, e.g. {"Authorization": "Bearer your-token"} |
| Body Template | Optional. Custom request body with {token} placeholders. Leave empty to send the full event payload as default JSON. |
Template variables are substituted into the Body Template field (they are not applied to the URL or headers). Available tokens:
| Variable | Description |
|---|---|
{book.title} | Book title |
{book.author} | Book author |
{book.coverUrl} | Cover art URL |
{release.title} | Release name from the indexer |
{release.indexer} | Indexer that provided the release |
{release.size} | Release file size |
{download.path} | Download path |
{download.size} | Downloaded file size |
{import.libraryPath} | Library path where the book was imported |
{import.fileCount} | Number of files imported |
{error.message} | Error message (failure events only) |
{error.stage} | Stage where the error occurred (failure events only) |
{health.checkName} | Name of the health check (health-issue events only) |
{health.previousState} | Previous health state (health-issue events only) |
{health.currentState} | Current health state (health-issue events only) |
{health.message} | Health check detail message (health-issue events only) |
Example uses:
- Trigger an Audiobookshelf library scan after import
- Post to Slack or Teams via incoming webhooks
- Integrate with Home Assistant automations
- Hit any REST endpoint
Discord
Section titled “Discord”Sends rich embeds to a Discord channel via webhook URL.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| Webhook URL | Discord webhook URL |
| Include Cover Image | Whether to attach the book’s cover art as the embed thumbnail. Enabled by default. |
Embeds are color-coded by event:
- Blue — grab
- Orange — download complete
- Green — import
- Red — failure
- Dark orange — health issue
Cover art thumbnails are included when available.
Creating a Discord Webhook
Section titled “Creating a Discord Webhook”- Open your Discord server
- Go to Server Settings > Integrations > Webhooks
- Click New Webhook
- Choose the target channel and copy the webhook URL
Script
Section titled “Script”Executes a local shell script or command on the Narratorr host when an event fires.
In the UI this notifier type is labeled Custom Script.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| Script Path | Path to the script or command to execute |
| Timeout (seconds) | How long the script may run before it’s killed. Default: 30. Range: 1–300. |
The script receives event data two ways:
- stdin — full JSON payload
- Environment variables —
NARRATORR_EVENT,NARRATORR_BOOK_TITLE,NARRATORR_BOOK_AUTHOR, etc.
Scripts have a configurable timeout (default 30s, max 300s) — if the script doesn’t exit within that window, it’s killed.
Sends an email via SMTP when an event fires.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| SMTP Host | Hostname of your SMTP server |
| SMTP Port | SMTP server port. Default: 587 |
| Username | Username for SMTP authentication |
| Password | Password for SMTP authentication |
| Use TLS/SSL | Whether to connect using TLS/SSL. Off by default. |
| From Address | Sender email address |
| To Address | Recipient email address |
Telegram
Section titled “Telegram”Sends a message to a Telegram chat via a bot.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| Bot Token | Token for your Telegram bot |
| Chat ID | ID of the chat to send messages to |
Posts a message to a Slack channel via an incoming webhook URL.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| Webhook URL | Slack incoming webhook URL |
Pushover
Section titled “Pushover”Sends a push notification through Pushover.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| API Token | Pushover application API token |
| User Key | Pushover user (or group) key |
Publishes a notification to an ntfy topic.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| Topic | ntfy topic to publish to (required) |
| Server URL | ntfy server URL (optional; defaults to the public ntfy.sh server) |
| Access Token | Optional. Bearer token for protected or authenticated ntfy topics. |
| Priority | Optional. One of min, low, default, high, or max. Leave blank to use the server default. |
Gotify
Section titled “Gotify”Sends a message to a self-hosted Gotify server.
| Field | Description |
|---|---|
| Name | Display name for this notifier |
| Server URL | URL of your Gotify server |
| App Token | Gotify application token |
Managing Notifiers
Section titled “Managing Notifiers”- Enable/disable — each notifier has a toggle. Disable to temporarily silence without deleting.
- Test — sends a test payload to verify connectivity before you rely on it.
- Multiple events — a single notifier can subscribe to any combination of events.
- Multiple notifiers — multiple notifiers can subscribe to the same event. All fire independently.
If notifications aren’t firing, see Troubleshooting > Notifications not firing.