Shoutrrr

The Shoutrrr CLI provides a way to interact with notification services without writing Go code. You can use it to:

• send: Dispatch a notification using a service URL.
• verify: Check if a notification service URL is valid.
• generate: Create a notification service URL based on user input.
• docs: View documentation for specific services.
• completion: Generate shell autocompletion scripts.

shoutrrr

The generic service allows you to send notifications to any target that accepts a POST request, even if Shoutrrr does not have a dedicated service for it. This is useful for custom webhooks or internal APIs.

Note that the receiving end must be configured to interpret the payload sent by Shoutrrr.

generic://example.com/webhook

The userinfo part of the URL defines the login identity. You can provide either a localpart or a full Jabber ID (JID):

• Localpart: A localpart like alice is automatically converted to alice@host.
• Full JID: A full JID (e.g., alice%40jabber.example.com) is used as-is for authentication, while the host in the URL remains the TCP dial target.

Note: When using a full JID in the userinfo, the @ character must be URL-encoded as %40.

xmpp://alice%40jabber.example.com:secret@xmpp.example.com/?to=bob@jabber.example.com

You can extend the basic Mattermost URL to override default webhook settings such as the sender username, the target channel, or the notification icon.

Overriding User and Channel

Add a username before the host and a channel path after the token: mattermost://shoutrrrUser@your-domain.com/token/shoutrrrChannel

Customizing the Icon

Use the icon query parameter to change the notification icon. You can use either a Mattermost emoji name or a direct image URL:

• Emoji: ?icon=rocket
• Image URL: ?icon=https://example.com/logo.png

# Using an emoji icon
mattermost://your-domain.com/bywsw8zt5jgpte3nm65qjiru6h?icon=rocket

# Using a URL icon
mattermost://your-domain.com/bywsw8zt5jgpte3nm65qjiru6h?icon=https://example.com/logo.png

The Generic service forwards all query variables to the target endpoint, except for those reserved for Shoutrrr configuration.

To pass a reserved parameter (like template or method) as a literal query variable to your target, prefix it with an underscore (_).

Example: _contenttype=text/plain will forward contenttype=text/plain to the server as a query parameter, rather than attempting to set it as an HTTP header.

generic+https://example.com/api/v1/postStuff?_contenttype=text/plain

The service attempts to fetch max_message_length and max_topic_length from Zulip's register endpoint on the first send (with a 10s timeout).

If the request fails or returns zero values, the following fallbacks are used:

• Message content: 10,000 bytes.
• Topics: 60 characters.

Note on counting:

• Topic length is calculated using rune count (Unicode aware).
• Message content length is calculated using byte count.

Shoutrrr uses a pluggable architecture for outbound connections to allow developers to implement security policies like SSRF protection or custom proxy routing.

• types.SenderOptions.HTTPClient: When provided, this *http.Client is used by services that implement the types.HTTPClientSetter interface. This is the primary way to control HTTP/HTTPS traffic.
• types.SenderOptions.DialContext: When provided, this function is used by services that implement the types.DialContextSetter interface (such as SMTP and MQTT). This allows you to control the underlying TCP connection before TLS is applied.
• Concurrency: Any custom DialContext provided must be safe for concurrent use.
• Proxying: If you use a custom DialContext, you bypass the standard MQTT all_proxy setting; you must implement proxy logic within your custom dialer if required.

When using a Sender, methods like Send or SendItems return a slice of errors ([]error). Each error corresponds to a unique configured target. Errors are wrapped in *types.TargetError, which allows you to identify which specific URL failed.

errs := sender.Send("deploy complete", nil)
for i, err := range errs {
    if err == nil {
        continue
    }
    var targetErr *types.TargetError
    if errors.As(err, &targetErr) {
        // targetErr.URL contains the failing service URL
        log.Printf("failed to send to %s: %v", targetErr.URL, targetErr.Err)
    }
}

You can control the state of a PagerDuty incident using the action parameter:

• trigger (Default): Creates a new incident or updates an existing one. Use this for system failures, outages, or security alerts.
• acknowledge: Stops incident escalation and indicates an engineer is investigating. Use this when triage begins.
• resolve: Closes the incident and prevents further notifications. Use this when the service is restored.

You can extend the Rocket.chat URL to specify a sender, a target channel, or a specific recipient. This overrides the default webhook behavior.

To specify a sender and a channel: rocketchat://sender@your-domain.com/token/channel

To specify a sender and a recipient (user): rocketchat://sender@your-domain.com/token/@recipient

rocketchat://shoutrrrUser@your-domain.com/8eGdRzc9r4YYNyvge/2XYQcX9NBwJBKfQnphpebPcnXZcPEi32Nt4NKJfrnbhsbRfX/shoutrrrChannel

rocketchat://shoutrrrUser@your-domain.com/8eGdRzc9r4YYNyvge/2XYQcX9NBwJBKfQnphpebPcnXZcPEi32Nt4NKJfrnbhsbRfX/@shoutrrrReceiver

The date parameter allows you to set a custom timestamp. Shoutrrr automatically converts the input into ISO 8601 format for the Gotify API. If the format is invalid, Shoutrrr logs a warning and falls back to the server's current time.

Supported Formats:

• ISO 8601 with timezone (RFC3339): 2023-12-25T10:00:00Z
• ISO 8601 without timezone: 2023-12-25T10:00:00 (assumes UTC)
• Unix timestamp: 1703498400
• Basic date-time: 2023-12-25 10:00:00 (assumes UTC)

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=1703498400

Signal supports three types of recipients:

• Phone numbers: Must include the country code (e.g., +0987654321).
• Group IDs: Formatted as group.groupId.
• Usernames: Formatted as u:nickname.123.

Important Behavior: The Signal API rejects mixed recipient types in a single /v2/send request. Shoutrrr automatically handles this by splitting them: all phone numbers are sent in one request, all usernames in another, and each group in its own separate request. If a URL contains multiple types (e.g., phones and a group), Shoutrrr will perform multiple POST requests.