diff --git a/.gitbook/assets/apprise_notification.png b/.gitbook/assets/apprise_notification.png new file mode 100644 index 0000000..4a87ef9 Binary files /dev/null and b/.gitbook/assets/apprise_notification.png differ diff --git a/.gitbook/assets/db_notification.png b/.gitbook/assets/db_notification.png index 8fd19c6..05b928c 100644 Binary files a/.gitbook/assets/db_notification.png and b/.gitbook/assets/db_notification.png differ diff --git a/.gitbook/assets/mail_notification.png b/.gitbook/assets/mail_notification.png index e15973d..2e69842 100644 Binary files a/.gitbook/assets/mail_notification.png and b/.gitbook/assets/mail_notification.png differ diff --git a/.gitbook/assets/webhook_notification.png b/.gitbook/assets/webhook_notification.png new file mode 100644 index 0000000..8fad263 Binary files /dev/null and b/.gitbook/assets/webhook_notification.png differ diff --git a/SUMMARY.md b/SUMMARY.md index e33bc75..720bd4a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -34,7 +34,7 @@ * [Notifications](settings/notifications/README.md) * [Database](settings/notifications/database.md) * [Mail](settings/notifications/mail.md) - * [Telegram](settings/notifications/telegram.md) + * [Webhook](settings/notifications/webhook.md) ## 👀 Other diff --git a/other/commands.md b/other/commands.md index f3d14c4..7963490 100644 --- a/other/commands.md +++ b/other/commands.md @@ -20,10 +20,13 @@ Core commands exist at the framework level and might be extended to provide addi Application commands are built to extend Speedtest Tracker's functionality from the CLI. -
CommandDescription
app:installInstalls a fresh version of Speedtest Tracker. If you have an existing install this will delete all data.
app:ookla-list-serversGet a list of local Ookla speedtest servers.
app:user-change-roleChange the role for a user.
app:user-reset-passwordChange the password for a user.
app:versionSends a notification to the admin users when Speedtest Tracker is outdated.
+
CommandDescription
app:installInstalls a fresh version of Speedtest Tracker. If you have an existing install this will delete all data.
app:ookla-list-serversGet a list of local Ookla speedtest servers.
app:user-change-roleChange the role for a user.
app:user-reset-passwordChange the password for a user.
### Maintenance commands Maintenance commands help fix issues that might crop up over time.
CommandDescription
app:result-fix-statusesReviews the data payload of each result and corrects the status attribute.
+ + + diff --git a/other/speedtest-process.md b/other/speedtest-process.md index 503f0cb..ed20d23 100644 --- a/other/speedtest-process.md +++ b/other/speedtest-process.md @@ -4,12 +4,14 @@ Speedtest Tracker uses the [Official Ookla CLI](https://www.speedtest.net/apps/c {% stepper %} {% step %} + #### Waiting The speedtest run request was created but has not been started. {% endstep %} {% step %} + #### Started The speedtest process has been started by a queue worker. diff --git a/settings/notifications/README.md b/settings/notifications/README.md index 51a90b7..68501e6 100644 --- a/settings/notifications/README.md +++ b/settings/notifications/README.md @@ -1,5 +1,5 @@ # Notifications {% hint style="warning" %} -Database, mail and webhook notifications are considered "core" channels. We're currently working on integrating Apprise and all other notification channels should be considered deprecated. +Database, Mail and Webhook notifications are considered "core" channels. We're currently working on integrating Apprise and all other notification channels should be considered deprecated. {% endhint %} diff --git a/settings/notifications/apprise.md b/settings/notifications/apprise.md new file mode 100644 index 0000000..f5d7c98 --- /dev/null +++ b/settings/notifications/apprise.md @@ -0,0 +1,22 @@ +--- +hidden: true +--- + +# Apprise + +Speedtest Tracker uses [Apprise](https://github.com/caronc/apprise-api) to send notifications to a wide variety of messaging services with a simple, unified configuration. + +Apprise allows you to easily deliver alerts to popular platforms such as Discord, Slack, Telegram and many more. + +{% hint style="warning" %} +To use Apprise notifications, you must deploy the [Apprise API](https://github.com/caronc/apprise-api) service. This is out of scope of this documentation. +{% endhint %} + +

Apprise Settings

+ +
NameDescription
URLThis is the URL of your running Apprise API instance
Service URLThis is the URL of the service that will receive the notification. You can find a full list of supported services and how to format their URLs in the Apprise notification services documentation.
+ +### Triggers + +
NameDescription
On completed speedtestOn each successful speedtest a notification will be send to the application.
On absolute threshold failureOn any absolute threshold failure a notification will be send to the application.
+ diff --git a/settings/notifications/telegram.md b/settings/notifications/telegram.md deleted file mode 100644 index b2e1bbe..0000000 --- a/settings/notifications/telegram.md +++ /dev/null @@ -1,22 +0,0 @@ -# Telegram - -Notifications sent to the Telegram channel will be sent to the list of recipients. - -

Telegram settings

- -### Setting Up Telegram - -To configure Telegram for notifications you'll need to have a [Telegram](https://telegram.org/) account and follow the directions below. - -1. Create a Telegram bot by starting a message with `@BotFather`. -2. Using the bot's token ID to add the following variable in your `.env` file in your mounted data directory. `TELEGRAM_BOT_TOKEN=putyourtokenhere` -3. Next you'll need your own chat ID (hint: it's not the bot ID), start a chat with `@Get_Id_Bot` and add that to your "Recipients" list and click "Save". -4. Start a chat with your bot your created in step 1 to start receiving notification from yout Telegram bot. - -### Triggers - -
NameDescription
On completed speedtestOn each successful speedtest a notification will be send to the application.
On absolute threshold failureOn any absolute threshold failure a notification will be send to the application.
- -### Recipients - -A recipient is any valid Telegram chat ID, you can add one or many recipients that will receive notifications based on the triggers selected. diff --git a/settings/notifications/webhook.md b/settings/notifications/webhook.md new file mode 100644 index 0000000..6d35dd9 --- /dev/null +++ b/settings/notifications/webhook.md @@ -0,0 +1,62 @@ +# Webhook + +A webhook will send a JSON payload to a receiver of your choice + +

Webhook settings

+ +### Payload + +Payload sent for a completed test + +```json +{ + "result_id": 2, + "site_name": "Speedtest Tracker", + "service": "Ookla", + "serverName": "Speedtest", + "serverId": 12345, + "isp": "Speedtest Communications", + "ping": 6.7, + "download": 93281280, + "upload": 28769728, + "packetLoss": 0, + "speedtest_url": "https://docs.speedtest-tracker.dev", + "url": "http://localhost/admin/results" +} +``` + +Payload sent for a threshold failure + +```json +{ + "result_id": 8, + "site_name": "Speedtest Tracker", + "service": "Ookla", + "serverName": "Speedtest", + "serverId": 12345, + "isp": "Speedtest Communications", + "metrics": [ + { + "name": "Download", + "threshold": "1000 Mbps", + "value": "91.78 Mbps" + }, + { + "name": "Upload", + "threshold": "1000 Mbps", + "value": "28.18 Mbps" + }, + { + "name": "Ping", + "threshold": "2 ms", + "value": "6.41 ms" + } + ], + "speedtest_url": "https://docs.speedtest-tracker.dev", + "url": "http://localhost/admin/results" +} +``` + +### Triggers + +
NameDescription
On completed speedtestOn each successful speedtest a notification will be send to the application.
On absolute threshold failureOn any absolute threshold failure a notification will be send to the application.