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