| 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" |