Debian Codegraph @

docs/services/specialized/generic/index.md

raw
1 # Generic
2
3 The Generic service can be used for any target that is not explicitly supported by Shoutrrr, as long as it supports receiving the message via a POST request.
4 Usually, this requires customization on the receiving end to interpret the payload that it receives, and might not be a viable approach.
5
6 Common examples for use with service providers can be found under [examples](../../../examples/home-assistant/index.md).
7
8 ## Custom headers
9
10 You can add additional HTTP headers to your request by adding query variables prefixed with `@` (`@key=value`).
11
12 For example, the following URL adds the `Accept-Language: tlh-Piqd` header:
13
14 ```url
15 generic://example.com?@acceptLanguage=tlh-Piqd
16 ```
17
18 The following adds webhook-specific information:
19
20 !!! example
21 ```url
22 generic://api.example.com/webhook?@Authorization=Bearer%20token123&@X-Custom=value
23 ```
24
25 !!! note
26 Header names are normalized to HTTP header format (e.g., `acceptlanguage` becomes `Accept-Language`).
27
28 ## JSON template
29
30 By using the built-in `JSON` template (`template=json`) you can create a generic JSON payload.
31 The keys used for `title` and `message` can be overridden by supplying the params/query values `titleKey` and `messageKey`.
32
33 !!! example
34 ```json
35 {
36 "title": "Oh no!",
37 "message": "The thing happened and now there is stuff all over the area!"
38 }
39 ```
40
41 !!! example
42 ```url
43 generic://api.example.com/webhook?template=json
44 ```
45
46 ### Custom data fields
47
48 When using the JSON template, you can add additional key/value pairs to the JSON object by adding query variables prefixed with `$` (`$key=value`).
49
50 !!! example
51 Using `generic://example.com?$projection=retroazimuthal` would yield:
52 ```json
53 {
54 "title": "Amazing opportunities!",
55 "message": "New map book available for purchase.",
56 "projection": "retroazimuthal"
57 }
58 ```
59
60 !!! example
61 ```url
62 generic://webhook.example.com/alert?$source=shoutrrr
63 ```
64
65 ## Shortcut URL
66
67 You can just add `generic+` as a prefix to your target URL to use it with the generic service.
68
69 For example, the following URL:
70
71 ```url
72 https://example.com/api/v1/postStuff
73 ```
74
75 Becomes the following `generic+` URL:
76
77 ```url
78 generic+https://example.com/api/v1/postStuff
79 ```
80
81 !!! Note
82 Any query variables added to the URL will be escaped so that they can be forwarded to the remote server. That means that you cannot use `?template=json` with the `generic+https://`, just use `generic://` instead!
83
84 !!! example
85 ```url
86 generic+https://example.com/api/v1/postStuff
87 ```
88
89 ## Forwarded query variables
90
91 All query variables that are not listed in the [Query/Param Props](#queryparam_props) section will be forwarded to the target endpoint.
92 If you need to pass a query variable that _is_ reserved, you can prefix it with an underscore (`_`).
93
94 !!! Example
95 The URL `generic+https://example.com/api/v1/postStuff?contenttype=text/plain` would send a POST message to `https://example.com/api/v1/postStuff` using the `Content-Type: text/plain` header.
96 If instead escaped, `generic+https://example.com/api/v1/postStuff?_contenttype=text/plain` would send a POST message to `https://example.com/api/v1/postStuff?contenttype=text/plain` using the `Content-Type: application/json` header (as it's the default).
97
98 !!! example
99 ```url
100 generic://webhook.example.com/alert?template=json&disabletls=yes&method=POST&titlekey=alert_title&messagekey=alert_message
101 ```
102
103 ## URL Format
104
105 --8<-- "docs/services/specialized/generic/config.md"