From 3e476868b1376826b498263c6539139b51f26092 Mon Sep 17 00:00:00 2001 From: sct Date: Tue, 12 Jan 2021 22:14:59 +0900 Subject: [PATCH] docs: notification agent docs added --- docs/SUMMARY.md | 16 ++++-- docs/using-overseerr/notifications/README.md | 28 ++++++++++ .../using-overseerr/notifications/webhooks.md | 56 +++++++++++++++++++ 3 files changed, 94 insertions(+), 6 deletions(-) create mode 100644 docs/using-overseerr/notifications/README.md create mode 100644 docs/using-overseerr/notifications/webhooks.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 6b98b1a5a..1685fc9b1 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -1,17 +1,21 @@ # Table of contents -* [Introduction](README.md) +- [Introduction](README.md) ## Getting Started -* [Installation](getting-started/installation.md) +- [Installation](getting-started/installation.md) + +## Using Overseerr + +- [Notifications](using-overseerr/notifications/README.md) + - [Custom Webhooks](using-overseerr/notifications/webhooks.md) ## Support -* [Frequently Asked Questions](support/faq.md) -* [Asking for Support](support/asking-for-support.md) +- [Frequently Asked Questions](support/faq.md) +- [Asking for Support](support/asking-for-support.md) ## Extending Overseerr -* [Reverse Proxy Examples](extending-overseerr/reverse-proxy-examples.md) - +- [Reverse Proxy Examples](extending-overseerr/reverse-proxy-examples.md) diff --git a/docs/using-overseerr/notifications/README.md b/docs/using-overseerr/notifications/README.md new file mode 100644 index 000000000..613236350 --- /dev/null +++ b/docs/using-overseerr/notifications/README.md @@ -0,0 +1,28 @@ +# Notifications + +Overseerr already supports a good number of notification agents, such as **Discord**, **Slack** and **Pushover**. New agents are always considered for development, if there is enough demand for it. + +## Currently Supported Notification Agents + +- Email +- Discord +- Slack +- Telegram +- Pushover +- [Webhooks](./webhooks.md) + +## Setting up Notifications + +Configuring your notifications is _very simple_. First, you will need to visit the **Settings** page and click **Notifications** in the menu. This will present you with all of the currently available notification agents. Click on each one individually to configure them. + +You must configure which type of notifications you want to send _per agent_. If no types are selected, you will not receive any notifications! + +Some agents may have specific configuration gotchas that will be covered in each notification agents documentation page. + +{% hint style="danger" %} +Currently, you will **not receive notifications** for any auto-approved requests. However, you will still receive a notification when the media becomes available. +{% endhint %} + +## Requesting new agents + +If we do not currently support a notification agent you would like, feel free to request it on our [GitHub Issues](https://github.com/sct/overseerr/issues). Make sure to search first to see if someone else already requested it! diff --git a/docs/using-overseerr/notifications/webhooks.md b/docs/using-overseerr/notifications/webhooks.md new file mode 100644 index 000000000..9f563b4c7 --- /dev/null +++ b/docs/using-overseerr/notifications/webhooks.md @@ -0,0 +1,56 @@ +# Webhooks + +Webhooks let you post a custom JSON payload to any endpoint you like. You can also set an authorization header for security purposes. + +## Configuration + +The following configuration options are available: + +### Webhook URL (Required) + +The URL you would like to post notifications to. Your JSON will be sent as the body of the request. + +### Authorization Header + +Custom authorization header. Anything entered for this will be sent as an `Authorization` header. + +### Custom JSON Payload (Required) + +Design your JSON payload as you see fit. JSON is validated before you can save or test. Overseerr provides several [template variables](./webhooks.md#template-variables) for use in the payload which will be replaced with actual values when the notifications are sent. + +You can always reset back to the default custom payload setting by clicking the `Reset to Default JSON Payload` button under the editor. + +## Template Variables + +### Main + +- `{{notification_type}}` The type of notification. (Ex. `MEDIA_PENDING` or `MEDIA_APPROVED`) +- `{{subject}}` The notification subject message. (For request notifications, this is the media title) +- `{{message}}` Notification message body. (For request notifications, this is the media's overview/synopsis) +- `{{image}}` Associated image with the request. (For request notifications, this is the media's poster) + +### Notify User + +These variables are usually the target user of the notification. + +- `{{notifyuser_username}}` Target user's username. +- `{{notifyuser_email}}` Target user's email. +- `{{notifyuser_avatar}}` Target user's avatar. + +### Media + +These variables are only included in media related notifications, such as requests. + +- `{{media_type}}` Media type. Either `movie` or `tv`. +- `{{media_tmdbid}}` Media's TMDB ID. +- `{{media_imdbid}}` Media's IMDB ID. +- `{{media_tvdbid}}` Media's TVDB ID. +- `{{media_status}}` Media's availability status. (Ex. `AVAILABLE` or `PENDING`) +- `{{media_status4k}}` Media's 4K availability status. (Ex. `AVAILABLE` or `PENDING`) + +### Special Key Variables + +These variables must be used as a key in the JSON Payload. (Ex, `"{{extra}}": []`). + +- `{{extra}}` This will override the value of the property to be the pre-formatted "extra" array that can come along with certain notifications. Using this variable is _not required_. +- `{{media}}` This will override the value of the property to `null` if there is no media object passed along with the notification.