Debian Codegraph @

docs/services/push/gotify/index.md

raw
1 # Gotify
2
3 Shoutrrr integrates with Gotify to enable sending notifications from command-line tools, scripts, or applications.
4
5 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.
6
7 For more information about Gotify, visit the [official Gotify documentation](https://gotify.net/docs/).
8
9 ## URL Format
10
11 --8<-- "docs/services/push/gotify/config.md"
12
13 ## API Endpoint
14
15 Shoutrrr sends notifications to Gotify using the REST API endpoint `POST /message`.
16 The request includes the notification data as JSON in the request body and uses either URL query parameters or HTTP headers for authentication.
17
18 ## Configuration Parameters
19
20 ### Token Requirements
21
22 !!! Note
23 Tokens are generated within the Gotify web interface when creating applications.
24
25 The Gotify application token must be exactly 15 characters long and must start with the letter 'A'.
26 It can contain uppercase and lowercase letters, numbers, and the special characters '.', '-', and '_'.
27
28 !!! Warning "Token Validation"
29 Invalid tokens will result in notification delivery failures. Always verify your token format matches Gotify's requirements.
30
31 ### Extras Field Support
32
33 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.
34
35 !!! Example "With extras for actions"
36
37 ```uri
38 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
39 ```
40
41 This sends a notification with an action button that opens `https://example.com` when clicked.
42
43 !!! Example "With extras for images"
44
45 ```uri
46 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&extras=%7B%22image%22%3A%22https%3A%2F%2Fexample.com%2Fimage.png%22%7D
47 ```
48
49 This includes an image URL in the notification.
50
51 ### Disable TLS
52
53 The `disabletls` parameter can be set to `yes` to disable TLS entirely, forcing the use of HTTP instead of HTTPS. This is useful for:
54
55 - Self-signed certificates in development environments
56 - Internal Gotify servers with custom CA certificates
57 - Testing with local Gotify instances
58
59 !!! danger "Security Risk"
60 Disabling TLS makes all communication unencrypted and vulnerable to interception. Only use this option in trusted, isolated networks.
61
62 ### Skip TLS Certificate Verification
63
64 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:
65
66 - Self-signed certificates in development environments
67 - Internal Gotify servers with custom CA certificates
68 - Testing with certificates that don't match the hostname
69
70 !!! danger "Security Risk"
71 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.
72
73 ### Priority Levels
74
75 Gotify supports priority levels to control how notifications are displayed and handled:
76
77 - **-2**: Very low priority (may be hidden in some clients)
78 - **-1**: Low priority
79 - **0**: Normal priority (default)
80 - **1**: High priority
81 - **2 to 10**: Very high priority (may trigger special handling like persistent notifications)
82
83 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.
84
85 ### Custom Title
86
87 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.
88
89 ### Custom Date
90
91 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.
92
93 #### Supported Input Formats
94
95 The date parameter accepts the following formats:
96
97 - **ISO 8601 with timezone** (RFC3339): `2023-12-25T10:00:00Z` or `2023-12-25T10:00:00+05:00`
98 - **ISO 8601 without timezone**: `2023-12-25T10:00:00` (assumes UTC)
99 - **Unix timestamp** (seconds since epoch): `1703498400`
100 - **Basic date-time**: `2023-12-25 10:00:00` (assumes UTC)
101
102 All formats are converted to ISO 8601 format before sending to Gotify.
103
104 #### Validation Behavior
105
106 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.
107
108 #### Use Cases
109
110 This parameter is useful for:
111
112 - Backdating notifications for historical events
113 - Ensuring consistent timestamps across multiple notifications
114 - Testing notification ordering in development
115 - Scheduling notifications with specific timestamps
116
117 !!! Example "ISO 8601 with timezone"
118
119 ```uri
120 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25T10:00:00Z
121 ```
122
123 Sets the notification timestamp to Christmas morning 2023 UTC.
124
125 !!! Example "ISO 8601 without timezone"
126
127 ```uri
128 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25T10:00:00
129 ```
130
131 Sets the notification timestamp to Christmas morning 2023, interpreted as UTC.
132
133 !!! Example "Unix timestamp"
134
135 ```uri
136 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=1703498400
137 ```
138
139 Sets the notification timestamp to Christmas morning 2023 (Unix timestamp for 2023-12-25 10:00:00 UTC).
140
141 !!! Example "Basic date-time format"
142
143 ```uri
144 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25%2010:00:00
145 ```
146
147 Sets the notification timestamp to Christmas morning 2023, interpreted as UTC.
148
149 ### Use Header Authentication
150
151 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:
152
153 - Headers are less likely to be logged in server access logs
154 - Query parameters may appear in browser history or be exposed in URLs
155 - Headers are encrypted in HTTPS requests
156
157 !!! Example "Using header authentication"
158
159 ```uri
160 gotify://gotify.example.com/message?useheader=yes
161 ```
162
163 This sends the token in the `X-Gotify-Key` header, with no token appearing in the URL.
164
165 ## Input Validation
166
167 Shoutrrr validates input parameters before sending notifications to Gotify to ensure data integrity and prevent common errors.
168
169 ### Message Requirements
170
171 Messages must contain at least one character. Empty messages are not allowed.
172
173 !!! Failure "Validation Failure Example"
174 ```bash
175 shoutrrr send --url "gotify://example.com/message?token=token" --message ""
176 ```
177 **Error**: `message cannot be empty`
178
179 ### Priority Ranges
180
181 Priority values must be integers between -2 and 10 inclusive. Values outside this range will be rejected.
182
183 !!! Failure "Validation Failure Example"
184 ```bash
185 shoutrrr send --url "gotify://example.com/message?token=token&priority=15" --message "test"
186 ```
187 **Error**: `priority must be between -2 and 10`
188
189 ### Date Format Handling
190
191 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.
192
193 !!! Failure "Validation Failure Example"
194 ```bash
195 shoutrrr send --url "gotify://example.com/message?token=token&date=invalid-date" --message "test"
196 ```
197 **Warning logged**: `invalid date format`
198 **Result**: Notification sent with server timestamp
199
200 Supported formats include:
201
202 - ISO 8601 with timezone: `2023-12-25T10:00:00Z`
203 - ISO 8601 without timezone: `2023-12-25T10:00:00`
204 - Unix timestamp: `1703498400`
205 - Basic date-time: `2023-12-25 10:00:00`
206
207 ## Examples
208
209 !!! Example "Common usage"
210
211 ```uri
212 gotify://gotify.example.com:443/message?token=AzyoeNS.D4iJLVa&title=Great+News&priority=1
213 ```
214
215 !!! Example "With subpath"
216 ```uri
217 gotify://example.com:443/path/to/gotify/message?token=AzyoeNS.D4iJLVa&title=Great+News&priority=1
218 ```
219
220 !!! Example "With all parameters"
221 ```uri
222 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
223 ```
224
225 !!! Example "Minimal configuration"
226 ```uri
227 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa
228 ```
229
230 !!! Example "With custom title and low priority"
231 ```uri
232 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&title=Info&priority=-1
233 ```
234
235 !!! Example "With custom date"
236 ```uri
237 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25T10%3A00%3A00Z&title=Scheduled+Event
238 ```
239
240 !!! Example "With Unix timestamp date"
241 ```uri
242 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=1703498400&title=Timestamp+Event
243 ```
244
245 !!! Example "With basic date-time format"
246 ```uri
247 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&date=2023-12-25%2010%3A00%3A00&title=Simple+Date+Event
248 ```
249
250 !!! Example "With TLS disabled for self-signed certificates"
251 ```uri
252 gotify://gotify.example.com:8080/message?token=AzyoeNS.D4iJLVa&disabletls=yes
253 ```
254
255 !!! Example "With TLS certificate verification skipped"
256 ```uri
257 gotify://gotify.example.com/message?token=AzyoeNS.D4iJLVa&insecureskipverify=yes
258 ```
259
260 ## Security Considerations
261
262 ### Authentication Security
263
264 - **Use header authentication** (`useheader=yes`) whenever possible to avoid exposing tokens in URLs
265 - Store URLs containing tokens securely and avoid sharing them in logs or version control
266 - Rotate tokens regularly through the Gotify web interface
267
268 ### Network Security
269
270 - Always use HTTPS (default) for production deployments
271 - Only disable TLS (`disabletls=yes`) or skip certificate verification (`insecureskipverify=yes`) in trusted development environments
272 - Consider using Gotify behind a reverse proxy with additional authentication layers
273
274 ### Token Management
275
276 - Tokens are application-specific in Gotify
277 - Each application can have its own token with specific permissions
278 - Delete unused applications and tokens immediately
279
280 ## Troubleshooting
281
282 ### Common Issues
283
284 #### Connection Failed
285
286 **Error**: `failed to send notification to Gotify`
287
288 **Possible causes:**
289
290 - Invalid or unreachable server URL
291 - Network connectivity issues
292 - Firewall blocking outbound connections
293
294 **Solutions:**
295
296 - Verify the Gotify server is running and accessible
297 - Check network connectivity and firewall rules
298 - Ensure the correct host and port are specified
299
300 #### Authentication Failed
301
302 **Error**: `invalid gotify token`
303
304 **Possible causes:**
305
306 - Incorrect token format (must be 15 chars starting with 'A')
307 - Token has been revoked or expired
308 - Wrong token for the application
309
310 **Solutions:**
311
312 - Verify token format: exactly 15 characters, starts with 'A'
313 - Regenerate token in Gotify web interface
314 - Ensure you're using the correct application token
315
316 #### TLS Certificate Issues
317
318 **Error**: TLS certificate verification failed
319
320 **Solutions:**
321
322 - For self-signed certificates, use `insecureskipverify=yes` to skip verification while maintaining HTTPS
323 - For development/testing with HTTP, use `disabletls=yes` to disable TLS entirely
324 - Install proper certificates on the Gotify server
325 - Verify the certificate is valid and not expired
326
327 #### Validation Errors
328
329 ##### Empty Messages
330
331 **Error**: `message cannot be empty`
332
333 **Possible causes:**
334
335 - No message provided in the request
336 - Message parameter is an empty string
337
338 **Solutions:**
339
340 - Always include a non-empty message in your notification
341 - Check that your message parameter is properly set
342
343 ##### Invalid Priorities
344
345 **Error**: `priority must be between -2 and 10`
346
347 **Possible causes:**
348
349 - Priority value is less than -2 or greater than 10
350 - Priority parameter contains non-numeric characters
351
352 **Solutions:**
353
354 - Use integer values between -2 and 10
355 - Verify the priority parameter is a valid number
356
357 ##### Malformed Extras JSON
358
359 **Error**: `failed to unmarshal extras JSON` or `failed to parse extras JSON from URL query`
360
361 **Possible causes:**
362
363 - Invalid JSON syntax in the extras parameter
364 - Improper URL encoding of the JSON string
365 - Missing quotes or brackets in JSON structure
366
367 **Solutions:**
368
369 - Validate JSON syntax using a JSON validator
370 - Ensure proper URL encoding when passing JSON in URLs
371 - Test extras JSON separately before including in URLs
372
373 ##### Invalid Date Formats
374
375 **Error**: `invalid date format` (logged as warning)
376
377 **Possible causes:**
378
379 - Date format not matching supported formats
380 - Invalid date values (e.g., February 30th)
381 - Incorrect timezone specifications
382
383 **Solutions:**
384
385 - Use one of the supported date formats listed above
386 - Verify date values are valid calendar dates
387 - Note that invalid dates still send notifications but use server timestamps
388
389 #### Error Handling Patterns
390
391 Shoutrrr employs several error handling strategies for malformed inputs:
392
393 - **Early Validation**: Parameters are validated before API requests to fail fast
394 - **Graceful Degradation**: Non-critical validation failures (like invalid dates) allow notifications to proceed with defaults
395 - **Detailed Error Messages**: Specific error messages help identify the exact validation issue
396 - **Fallback Behavior**: When possible, invalid inputs fall back to sensible defaults rather than failing completely
397
398 ### Testing Your Configuration
399
400 You can test your Gotify configuration using the Shoutrrr CLI:
401
402 ```bash
403 shoutrrr verify --url "gotify://your-server/message?token=token"
404 ```
405
406 This validates the URL format and service configuration. To send a test notification, use:
407
408 ```bash
409 shoutrrr send --url "gotify://your-server/message?token=token" --message "Test notification"
410 ```
411
412 ### Gotify Server Logs
413
414 Check the Gotify server logs for additional error details. Common log locations:
415
416 - Docker: `docker logs gotify_container`
417 - Systemd: `journalctl -u gotify`
418 - Binary: Check the log file specified in your Gotify configuration
419
420 ### Getting Help
421
422 - Check the [Gotify documentation](https://gotify.net/docs/) for server setup and configuration
423 - Report issues on the [Shoutrrr GitHub repository](https://github.com/nicholas-fedor/shoutrrr)