Shoutrrr
July 7, 2026 · View on GitHub
Shoutrrr
A notification library for gophers and their furry friends.
Heavily inspired by caronc/apprise.
Table of Contents
Full Documentation
Visit the project's GitHub Page for full documentation.
Installation
From Source
go install github.com/nicholas-fedor/shoutrrr/shoutrrr@latest
Binaries
Install the latest release binary to $HOME/go/bin (ensure it's in your PATH).
-
Windows (amd64):
New-Item -ItemType Directory -Path $HOME\go\bin -Force | Out-Null; iwr (iwr https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | ConvertFrom-Json).assets.where({$_.name -like "*windows_amd64*.zip"}).browser_download_url -OutFile shoutrrr.zip; Add-Type -AssemblyName System.IO.Compression.FileSystem; ($z=[System.IO.Compression.ZipFile]::OpenRead("$PWD\shoutrrr.zip")).Entries | ? {$_.Name -eq 'shoutrrr.exe'} | % {[System.IO.Compression.ZipFileExtensions]::ExtractToFile($_, "$HOME\go\bin\$($_.Name)", $true)}; $z.Dispose(); rm shoutrrr.zip; if (Test-Path "$HOME\go\bin\shoutrrr.exe") { Write-Host "Successfully installed shoutrrr.exe to $HOME\go\bin" } else { Write-Host "Failed to install shoutrrr.exe" } -
Linux (amd64):
mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*linux_amd64[^"]*\.tar\.gz"' | grep -o 'https://[^"]*' | head -n1) | tar -xz -C $HOME/go/bin shoutrrr -
macOS (amd64):
mkdir -p $HOME/go/bin && curl -L $(curl -s https://api.github.com/repos/nicholas-fedor/shoutrrr/releases/latest | grep -o 'https://[^"]*macOS_amd64[^"]*\.tar\.gz"' | grep -o 'https://[^"]*' | head -n1) | tar -xz -C $HOME/go/bin shoutrrr
Note
Visit the releases page for other architectures (e.g., arm, arm64, i386, riscv64).
Container Images
-
docker pull nickfedor/shoutrrr:latest -
GHCR:
docker pull ghcr.io/nicholas-fedor/shoutrrr:latest
Note
Tags: latest (stable), vX.Y.Z (specific version), nightly (development), platform-specific (e.g., amd64-nightly).
Go Package
go get github.com/nicholas-fedor/shoutrrr@latest
GitHub Action
- name: Shoutrrr
uses: nicholas-fedor/shoutrrr-action@v1
with:
url: ${{ secrets.SHOUTRRR_URL }}
title: Deployed ${{ github.sha }}
message: See changes at ${{ github.event.compare }}.
Usage
CLI
shoutrrr send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"
Go Package Usage
import "github.com/nicholas-fedor/shoutrrr"
errs := shoutrrr.Send("slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook", "Hello, Slack!")
if len(errs) > 0 {
// Handle errors
}
Docker
docker run --rm nickfedor/shoutrrr:latest send --url "slack://hook:T00000000-B00000000-XXXXXXXXXXXXXXXXXXXXXXXX@webhook" --message "Hello, Slack!"
GitHub Action Usage
See installation example above.
Use as a Package
Option 1 - Using the direct send command
url := "slack://token-a/token-b/token-c"
err := shoutrrr.Send(url, "Hello world (or slack channel) !")
Option 2 - Using a sender
Single URL
url := "slack://token-a/token-b/token-c"
sender, err := shoutrrr.CreateSender(url)
sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })
Multiple URLs
urls := []string {
"slack://token-a/token-b/token-c"
"discord://token@channel"
}
sender, err := shoutrrr.CreateSender(urls...)
sender.Send("Hello world (or slack channel) !", map[string]string { /* ... */ })
Custom HTTP Client (SSRF / Egress Control)
import (
"crypto/tls"
"log"
"net/http"
"github.com/nicholas-fedor/shoutrrr"
"github.com/nicholas-fedor/shoutrrr/pkg/types"
)
customClient := &http.Client{
Transport: &http.Transport{
TLSClientConfig: &tls.Config{MinVersion: tls.VersionTLS12},
},
}
sender, err := shoutrrr.NewSenderWithOptions(
nil,
types.SenderOptions{HTTPClient: customClient},
"discord://token@channel",
)
if err != nil {
log.Fatal(err)
}
sender.Send("Hello with custom egress!", nil)
Use Through the CLI
shoutrrr send [OPTIONS] <URL> <Message [...]>
Use as a GitHub Action
You can also use Shoutrrr in a GitHub Actions workflow.
name: Deploy
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- [Your other workflow steps]
- name: Shoutrrr
uses: nicholas-fedor/shoutrrr-action@v0.0.11
with:
url: ${{ secrets.SHOUTRRR_URL }}
title: Deployed ${{ github.sha }}
message: See changes at ${{ github.event.compare }}.
Supported Services
| Service | Description |
|---|---|
| Bark | iOS push notifications |
| Discord | Discord webhooks |
| Generic | Custom HTTP webhooks |
| Google Chat | Google Chat webhooks |
| Gotify | Gotify push notifications |
| IFTTT | IFTTT webhooks |
| Join | Join push notifications |
| Lark | Lark (Feishu) webhooks |
| Logger | Local logging (for testing) |
| Matrix | Matrix rooms |
| Mattermost | Mattermost webhooks |
| MQTT | MQTT message broker |
| Notifiarr | Notifiarr message forwarding |
| Ntfy | Ntfy push notifications |
| Opsgenie | Opsgenie alerts |
| PagerDuty | PagerDuty incident notifications |
| Pushbullet | Pushbullet push notifications |
| Pushover | Pushover push notifications |
| Rocket.Chat | Rocket.Chat webhooks |
| Slack | Slack webhooks or Bot API |
| SMTP | Email notifications |
| Teams | Microsoft Teams webhooks |
| Telegram | Telegram bots |
| Twilio | Twilio SMS notifications |
| Zulip | Zulip chat |
| XMPP | XMPP messages (if enabled) |
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Related Project(s)
- Watchtower - Automate Docker container image updates.
- Shoutrrr GitHub Action - Notifications using Shoutrrr in GitHub Actions.
- Bezel - A lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions.
- WatchYourLAN - Lightweight network IP scanner with web GUI.
- DNSControl- Infrastructure as code for DNS.
- docker-volume-backup - Backup Docker volumes locally or to any S3, WebDAV, Azure Blob Storage, Dropbox, Google Drive or SSH compatible storage.
- BirdNET-Go - An AI solution for continuous avian monitoring and identification.