Gotify¶

Shoutrrr integrates with Gotify to enable sending notifications from command-line tools, scripts, or applications.

Gotify is a self-hosted notification service that allows you to send push notifications to your devices. It provides a simple REST API for sending messages and supports various features like priorities, custom titles, and additional metadata through extras.

For more information about Gotify, visit the official Gotify documentation.

URL Format¶

URL Fields¶

Host - Server hostname (and optionally port) (Required)
URL part: gotify://host:port/path/token
Path - Server subpath
Default: empty
URL part: gotify://host:port/path/token
Token - Application token (Required)
URL part: gotify://host:port/path/token

Query/Param Props¶

Props can be either supplied using the params argument, or through the URL using
?key=value&key=value etc.

Extras (Required)
Date
Default: empty
DisableTLS
Default: ❌ No
InsecureSkipVerify
Default: ❌ No
Priority
Default: 0
Title
Default: Shoutrrr notification
UseHeader - Enable header-based authentication
Default: ❌ No

API Endpoint¶

Shoutrrr sends notifications to Gotify using the REST API endpoint POST /message. The request includes the notification data as JSON in the request body and uses either URL query parameters or HTTP headers for authentication.

Configuration Parameters¶

Token Requirements¶

Note

Tokens are generated within the Gotify web interface when creating applications.

The Gotify application token must be exactly 15 characters long and must start with the letter 'A'. It can contain uppercase and lowercase letters, numbers, and the special characters '.', '-', and '_'.

Token Validation

Invalid tokens will result in notification delivery failures. Always verify your token format matches Gotify's requirements.

Extras Field Support¶

The extras parameter allows you to include additional metadata in the notification payload sent to Gotify. This is passed as a JSON object and can be used for features like actions, images, or custom data that Gotify supports.

With extras for actions

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&extras=%7B%22action%22%3A%22view%22%2C%22url%22%3A%22https%3A%2F%2Fexample.com%22%7D

This sends a notification with an action button that opens https://example.com when clicked.

With extras for images

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&extras=%7B%22image%22%3A%22https%3A%2F%2Fexample.com%2Fimage.png%22%7D

This includes an image URL in the notification.

Disable TLS¶

The disabletls parameter can be set to yes to disable TLS entirely, forcing the use of HTTP instead of HTTPS. This is useful for:

Self-signed certificates in development environments
Internal Gotify servers with custom CA certificates
Testing with local Gotify instances

Security Risk

Disabling TLS makes all communication unencrypted and vulnerable to interception. Only use this option in trusted, isolated networks.

Skip TLS Certificate Verification¶

The insecureskipverify parameter can be set to yes to skip TLS certificate verification while still using HTTPS. This maintains encrypted communication but bypasses certificate validation. This is useful for:

Self-signed certificates in development environments
Internal Gotify servers with custom CA certificates
Testing with certificates that don't match the hostname

Security Risk

Skipping certificate verification makes connections vulnerable to man-in-the-middle attacks. Only use this option when you trust the network path to the server.

Priority Levels¶

Gotify supports priority levels to control how notifications are displayed and handled:

-2: Very low priority (may be hidden in some clients)
-1: Low priority
0: Normal priority (default)
1: High priority
2 to 10: Very high priority (may trigger special handling like persistent notifications)

Higher priority notifications typically appear more prominently and may bypass quiet hours or notification filters. The priority can be set to a value between -2 and 10, where -2 is the lowest priority and 10 is the highest. Negative values have special meanings in some clients.

Custom Title¶

The title parameter allows you to set a custom title for your notification. If not specified, Shoutrrr uses the default title "Shoutrrr notification". Titles should be concise and descriptive to help users quickly identify the notification's purpose.

Custom Date¶

The date parameter allows you to set a custom timestamp for the notification. Shoutrrr accepts multiple common date formats and automatically converts them to ISO 8601 format for the Gotify API. If not specified, Gotify will use the current server time when the notification is received.

Supported Input Formats¶

The date parameter accepts the following formats:

ISO 8601 with timezone (RFC3339): 2023-12-25T10:00:00Z or 2023-12-25T10:00:00+05:00
ISO 8601 without timezone: 2023-12-25T10:00:00 (assumes UTC)
Unix timestamp (seconds since epoch): 1703498400
Basic date-time: 2023-12-25 10:00:00 (assumes UTC)

All formats are converted to ISO 8601 format before sending to Gotify.

Validation Behavior¶

If an invalid date format is provided, Shoutrrr will log a warning and skip setting the custom date, falling back to Gotify's default server timestamp. This ensures notifications are still delivered even with date parsing errors.

Use Cases¶

This parameter is useful for:

Backdating notifications for historical events
Ensuring consistent timestamps across multiple notifications
Testing notification ordering in development
Scheduling notifications with specific timestamps

ISO 8601 with timezone

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25T10:00:00Z

Sets the notification timestamp to Christmas morning 2023 UTC.

ISO 8601 without timezone

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25T10:00:00

Sets the notification timestamp to Christmas morning 2023, interpreted as UTC.

Unix timestamp

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

Sets the notification timestamp to Christmas morning 2023 (Unix timestamp for 2023-12-25 10:00:00 UTC).

Basic date-time format

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25%2010:00:00

Sets the notification timestamp to Christmas morning 2023, interpreted as UTC.

Use Header Authentication¶

By default, the Gotify token is sent as a query parameter in the URL (?token=...). The useheader parameter set to yes removes the token from the URL entirely and sends it in the X-Gotify-Key HTTP header instead, which provides better security since:

Headers are less likely to be logged in server access logs
Query parameters may appear in browser history or be exposed in URLs
Headers are encrypted in HTTPS requests

Using header authentication

gotify://gotify.example.com/message?useheader=yes

This sends the token in the X-Gotify-Key header, with no token appearing in the URL.

Input Validation¶

Shoutrrr validates input parameters before sending notifications to Gotify to ensure data integrity and prevent common errors.

Message Requirements¶

Messages must contain at least one character. Empty messages are not allowed.

Validation Failure Example

shoutrrr send --url "gotify://example.com/message?token=token" --message ""

Error: message cannot be empty

Priority Ranges¶

Priority values must be integers between -2 and 10 inclusive. Values outside this range will be rejected.

Validation Failure Example

shoutrrr send --url "gotify://example.com/message?token=token&priority=15" --message "test"

Error: priority must be between -2 and 10

Date Format Handling¶

Shoutrrr supports multiple date input formats, automatically converting them to ISO 8601 for the Gotify API. Invalid date formats are logged as warnings, and the notification uses Gotify's server timestamp instead.

Validation Failure Example

shoutrrr send --url "gotify://example.com/message?token=token&date=invalid-date" --message "test"

Warning logged: invalid date format Result: Notification sent with server timestamp

Supported formats include:

ISO 8601 with timezone: 2023-12-25T10:00:00Z
ISO 8601 without timezone: 2023-12-25T10:00:00
Unix timestamp: 1703498400
Basic date-time: 2023-12-25 10:00:00

Examples¶

Common usage

gotify://gotify.example.com:443/message?token=AzyoeNS.D4iJLVa&title=Great+News&priority=1

With subpath

gotify://example.com:443/path/to/gotify/message?token=AzyoeNS.D4iJLVa&title=Great+News&priority=1

With all parameters

gotify://gotify.example.com/message?title=System+Alert&priority=5&disabletls=yes&useheader=yes&date=2023-12-25T10%3A00%3A00Z&extras=%7B%22action%22%3A%22view%22%2C%22url%22%3A%22https%3A%2F%2Fexample.com%2Falert%22%2C%22image%22%3A%22https%3A%2F%2Fexample.com%2Falert.png%22%7D

Minimal configuration

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

With custom title and low priority

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&title=Info&priority=-1

With custom date

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25T10%3A00%3A00Z&title=Scheduled+Event

With Unix timestamp date

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=1703498400&title=Timestamp+Event

With basic date-time format

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25%2010%3A00%3A00&title=Simple+Date+Event

With TLS disabled for self-signed certificates

gotify://gotify.example.com:8080/message?token=AzyoeNS.D4iJLVa&disabletls=yes

With TLS certificate verification skipped

gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&insecureskipverify=yes

Security Considerations¶

Authentication Security¶

Use header authentication (useheader=yes) whenever possible to avoid exposing tokens in URLs
Store URLs containing tokens securely and avoid sharing them in logs or version control
Rotate tokens regularly through the Gotify web interface

Network Security¶

Always use HTTPS (default) for production deployments
Only disable TLS (disabletls=yes) or skip certificate verification (insecureskipverify=yes) in trusted development environments
Consider using Gotify behind a reverse proxy with additional authentication layers

Token Management¶

Tokens are application-specific in Gotify
Each application can have its own token with specific permissions
Delete unused applications and tokens immediately

Troubleshooting¶

Common Issues¶

Connection Failed¶

Error: failed to send notification to Gotify

Possible causes:

Invalid or unreachable server URL
Network connectivity issues
Firewall blocking outbound connections

Solutions:

Verify the Gotify server is running and accessible
Check network connectivity and firewall rules
Ensure the correct host and port are specified

Authentication Failed¶

Error: invalid gotify token

Possible causes:

Incorrect token format (must be 15 chars starting with 'A')
Token has been revoked or expired
Wrong token for the application

Solutions:

Verify token format: exactly 15 characters, starts with 'A'
Regenerate token in Gotify web interface
Ensure you're using the correct application token

TLS Certificate Issues¶

Error: TLS certificate verification failed

Solutions:

For self-signed certificates, use insecureskipverify=yes to skip verification while maintaining HTTPS
For development/testing with HTTP, use disabletls=yes to disable TLS entirely
Install proper certificates on the Gotify server
Verify the certificate is valid and not expired

Validation Errors¶

Empty Messages¶

Error: message cannot be empty

Possible causes:

No message provided in the request
Message parameter is an empty string

Solutions:

Always include a non-empty message in your notification
Check that your message parameter is properly set

Invalid Priorities¶

Error: priority must be between -2 and 10

Possible causes:

Priority value is less than -2 or greater than 10
Priority parameter contains non-numeric characters

Solutions:

Use integer values between -2 and 10
Verify the priority parameter is a valid number

Malformed Extras JSON¶

Error: failed to unmarshal extras JSON or failed to parse extras JSON from URL query

Possible causes:

Invalid JSON syntax in the extras parameter
Improper URL encoding of the JSON string
Missing quotes or brackets in JSON structure

Solutions:

Validate JSON syntax using a JSON validator
Ensure proper URL encoding when passing JSON in URLs
Test extras JSON separately before including in URLs

Invalid Date Formats¶

Error: invalid date format (logged as warning)

Possible causes:

Date format not matching supported formats
Invalid date values (e.g., February 30th)
Incorrect timezone specifications

Solutions:

Use one of the supported date formats listed above
Verify date values are valid calendar dates
Note that invalid dates still send notifications but use server timestamps

Error Handling Patterns¶

Shoutrrr employs several error handling strategies for malformed inputs:

Early Validation: Parameters are validated before API requests to fail fast
Graceful Degradation: Non-critical validation failures (like invalid dates) allow notifications to proceed with defaults
Detailed Error Messages: Specific error messages help identify the exact validation issue
Fallback Behavior: When possible, invalid inputs fall back to sensible defaults rather than failing completely

Testing Your Configuration¶

You can test your Gotify configuration using the Shoutrrr CLI:

shoutrrr verify --url "gotify://your-server/message?token=token"

This validates the URL format and service configuration. To send a test notification, use:

shoutrrr send --url "gotify://your-server/message?token=token" --message "Test notification"

Gotify Server Logs¶

Check the Gotify server logs for additional error details. Common log locations:

Docker: docker logs gotify_container
Systemd: journalctl -u gotify
Binary: Check the log file specified in your Gotify configuration

Getting Help¶

Check the Gotify documentation for server setup and configuration
Report issues on the Shoutrrr GitHub repository