Debian Codegraph @

pkg/services/specialized/generic/doc.go

raw
1 // Package generic provides a generic notification service for custom webhooks.
2 //
3 // The generic service allows sending notifications to any webhook endpoint that accepts
4 // HTTP POST requests, making it suitable for targets not explicitly supported by Shoutrrr.
5 // It supports flexible payload formatting through templates, custom headers, extra data,
6 // and various configuration options.
7 //
8 // # URL Format
9 //
10 // The service URL follows the format:
11 //
12 // generic://host[:port]/path[?query]
13 //
14 // Where:
15 // - host: the webhook endpoint hostname or IP address
16 // - port: optional port number (defaults to 443 for HTTPS, 80 for HTTP)
17 // - path: the webhook path
18 // - query: configuration parameters
19 //
20 // # Configuration Options
21 //
22 // The following query parameters can be used to configure the service:
23 //
24 // - template: payload template ("json" for JSON format, or custom template name)
25 // - contenttype: HTTP Content-Type header (default: "application/json")
26 // - method: HTTP method (default: "POST")
27 // - disabletls: set to "yes" to use HTTP instead of HTTPS
28 // - titlekey: JSON key for title field (default: "title")
29 // - messagekey: JSON key for message field (default: "message")
30 // - @HeaderName: custom HTTP headers (e.g., @Authorization=Bearer token)
31 // - $ExtraKey: extra data to include in JSON payload (e.g., $context=value)
32 //
33 // # Templates
34 //
35 // ## JSON Template
36 //
37 // When template=json, the payload is a JSON object containing the message and optional title:
38 //
39 // {
40 // "title": "Notification Title",
41 // "message": "Notification message"
42 // }
43 //
44 // Custom keys can be specified with titlekey and messagekey parameters.
45 //
46 // ## Custom Templates
47 //
48 // Custom templates can be registered using the service's template system.
49 // Templates use Go template syntax and receive the notification parameters as context.
50 //
51 // # Shortcut URLs
52 //
53 // For convenience, you can prefix any webhook URL with "generic+" to use the generic service:
54 //
55 // https://example.com/webhook → generic+https://example.com/webhook
56 //
57 // Note: Query parameters cannot be used with the shortcut format.
58 //
59 // # Examples
60 //
61 // ## Basic webhook notification
62 //
63 // url := "generic://api.example.com/webhook"
64 // err := shoutrrr.Send(url, "Hello, webhook!")
65 //
66 // ## JSON payload with custom headers
67 //
68 // url := "generic://api.example.com/webhook?template=json&@Authorization=Bearer token123"
69 // err := shoutrrr.Send(url, "Alert message", map[string]string{"title": "System Alert"})
70 //
71 // ## HTTP webhook with extra data
72 //
73 // url := "generic://192.168.1.100:8123/api/webhook?template=json&disabletls=yes&$context=home-assistant"
74 // err := shoutrrr.Send(url, "Motion detected")
75 //
76 // ## Custom template
77 //
78 // service := &generic.Service{}
79 // service.SetTemplateString("custom", `{"alert": "{{.message}}", "level": "info"}`)
80 // url := "generic://api.example.com/webhook?template=custom"
81 // err := service.Send("Custom alert message", nil)
82 //
83 // # Common Use Cases
84 //
85 // ## Home Assistant Integration
86 //
87 // Send notifications to Home Assistant webhooks:
88 //
89 // url := "generic://home-assistant.local:8123/api/webhook/webhook-id?template=json&disabletls=yes"
90 // err := shoutrrr.Send(url, "Front door opened")
91 //
92 // In Home Assistant automations, access the message with: {{ trigger.json.message }}
93 //
94 // ## Generic Webhook Service Integration
95 //
96 // Send notifications to any webhook service that accepts JSON payloads:
97 //
98 // url := "generic://your-service.com/api/webhook?template=json&@Authorization=Bearer YOUR_TOKEN"
99 // err := shoutrrr.Send(url, "Your notification message", map[string]string{"title": "Alert"})
100 //
101 // To adapt this template for your specific webhook service:
102 //
103 // 1. Replace "your-service.com" with your webhook endpoint hostname or IP address
104 // 2. Update the path "/api/webhook" to match your service's webhook path
105 // 3. Set the appropriate authorization header (e.g., Bearer token, API key, or custom header)
106 // 4. Adjust query parameters as needed for your service's requirements
107 // 5. Customize the title and message keys if your service expects different field names
108 // 6. Use disabletls=yes for HTTP endpoints or omit for HTTPS
109 //
110 // ## Custom API Endpoints
111 //
112 // Integrate with any REST API that accepts POST requests:
113 //
114 // url := "generic://api.service.com/notifications?@X-API-Key=your-key&template=json"
115 // err := shoutrrr.Send(url, "New order received", map[string]string{"order_id": "12345"})
116 //
117 // ## Monitoring Systems
118 //
119 // Send alerts to monitoring dashboards:
120 //
121 // url := "generic://monitoring.company.com/alerts?template=json&$source=shoutrrr"
122 // err := shoutrrr.Send(url, "Server CPU usage high", map[string]string{"severity": "warning"})
123 //
124 // # Error Handling
125 //
126 // The service returns errors for network failures, HTTP error status codes (4xx/5xx),
127 // and configuration issues. Always check the returned error:
128 //
129 // err := shoutrrr.Send(url, message)
130 // if err != nil {
131 // log.Printf("Failed to send notification: %v", err)
132 // }
133 //
134 // # Security Considerations
135 //
136 // - Use HTTPS whenever possible (avoid disabletls=yes in production)
137 // - Store API keys and tokens securely, not in URLs
138 // - Validate webhook endpoints before deployment
139 // - Consider rate limiting and authentication requirements of target services
140 package generic