Debian Codegraph @

pkg/services/push/ifttt/doc.go

raw
1 // Package ifttt provides a notification service for sending notifications via IFTTT webhooks.
2 //
3 // The IFTTT service allows sending notifications by triggering IFTTT (If This Then That) webhook
4 // events. When an event is triggered, IFTTT can execute any of its thousands of applets to send
5 // notifications via email, SMS, push notifications, or many other channels. This integration
6 // provides a flexible way to connect Shoutrrr with the extensive IFTTT ecosystem.
7 //
8 // For more information about IFTTT, visit https://ifttt.com/
9 //
10 // For more information about IFTTT Webhooks, visit https://ifttt.com/maker_webhooks
11 //
12 // # URL Format
13 //
14 // The service URL follows the format:
15 //
16 // ifttt://webhookID[?query]
17 //
18 // Where:
19 // - webhookID: IFTTT webhook key (required) - found at https://ifttt.com/maker_webhooks
20 // - query: configuration parameters
21 //
22 // # Configuration Options
23 //
24 // The following query parameters can be used to configure the service:
25 //
26 // - events: comma-separated list of IFTTT event names to trigger (required, at least one)
27 // - value1: custom value for the IFTTT payload (optional)
28 // - value2: custom value for the IFTTT payload (optional)
29 // - value3: custom value for the IFTTT payload (optional)
30 // - messagevalue: which value field (1-3) to use for the notification message (default: 2)
31 // - titlevalue: which value field (1-3) to use for the notification title, or 0 to disable (default: 0)
32 // - title: notification title to set (optional)
33 //
34 // # Templates
35 //
36 // IFTTT does not use templates in the Shoutrrr sense, but supports three value fields (value1,
37 // value2, value3) in its webhook payload. The notification message and title can be mapped to
38 // any of these fields using the messagevalue and titlevalue parameters respectively.
39 //
40 // # Usage Examples
41 //
42 // ## Basic notification
43 //
44 // url := "ifttt://my-webhook-key?events=test-event"
45 // err := shoutrrr.Send(url, "Hello from Shoutrrr!")
46 //
47 // ## Notification with custom values
48 //
49 // url := "ifttt://my-webhook-key?events=alert&value1=Server&value2=Down&value3=Critical"
50 // err := shoutrrr.Send(url, "Production server is down!")
51 //
52 // ## Notification with message in value1
53 //
54 // url := "ifttt://my-webhook-key?events=notification&messagevalue=1"
55 // err := shoutrrr.Send(url, "This message goes to Value1")
56 //
57 // ## Notification with title in value1 and message in value2
58 //
59 // url := "ifttt://my-webhook-key?events=alert&titlevalue=1&messagevalue=2"
60 // err := shoutrrr.Send(url, "Alert message here")
61 //
62 // ## Triggering multiple events
63 //
64 // url := "ifttt://my-webhook-key?events=email-alert,push-notification,sms-alert"
65 // err := shoutrrr.Send(url, "Critical system alert!")
66 //
67 // ## Notification with title parameter
68 //
69 // url := "ifttt://my-webhook-key?events=notification&title=System%20Alert"
70 // err := shoutrrr.Send(url, "Something needs your attention")
71 //
72 // # Common Use Cases
73 //
74 // ## System Monitoring Alerts
75 //
76 // Send alerts from monitoring systems like Nagios, Prometheus, or Zabbix to multiple notification
77 // channels through IFTTT applets:
78 //
79 // url := "ifttt://my-webhook-key?events=system-alert&value1=Disk%20Space&value2=95%25&value3=CRITICAL"
80 // err := shoutrrr.Send(url, "Disk space at 95% - immediate action required")
81 //
82 // ## CI/CD Pipeline Notifications
83 //
84 // Notify about build status from Jenkins, GitHub Actions, or GitLab CI:
85 //
86 // url := "ifttt://my-webhook-key?events=build-failed&value1=Build%20%23123&value2=main&value3=2m"
87 // err := shoutrrr.Send(url, "Build failed after running tests")
88 //
89 // ## Home Automation
90 //
91 // Integrate with home automation systems via IFTTT to send notifications to your phone,
92 // smart speaker, or other connected devices:
93 //
94 // url := "ifttt://my-webhook-key?events=home-automation&value1=Front%20Door&value2=Motion%20Detected"
95 // err := shoutrrr.Send(url, "Motion detected at front door")
96 //
97 // ## IoT Device Notifications
98 //
99 // Receive alerts from IoT devices and sensors:
100 //
101 // url := "ifttt://my-webhook-key?events=sensor-alert&value1=Temperature&value2=32C&value3=Living%20Room"
102 // err := shoutrrr.Send(url, "Temperature above threshold in Living Room")
103 //
104 // ## Calendar Reminders
105 //
106 // Trigger IFTTT applets for calendar events:
107 //
108 // url := "ifttt://my-webhook-key?events=meeting-reminder&value1=Team%20Standup&value2=10:00%20AM"
109 // err := shoutrrr.Send(url, "Reminder: Team standup in 15 minutes")
110 //
111 // ## Incident Response
112 //
113 // Send urgent notifications that trigger multiple IFTTT actions:
114 //
115 // url := "ifttt://my-webhook-key?events=incident,pagerduty,slack-alert&value1=Database&value2=Connection%20Lost&value3=P1"
116 // err := shoutrrr.Send(url, "Database connection lost - immediate attention required")
117 //
118 // # Error Handling
119 //
120 // The service returns errors for various failure scenarios. Always check the returned error:
121 //
122 // err := shoutrrr.Send(url, message)
123 // if err != nil {
124 // log.Printf("Failed to send IFTTT notification: %v", err)
125 // }
126 //
127 // Common error scenarios:
128 // - Missing webhook ID (required)
129 // - Missing events (required)
130 // - Invalid messagevalue (must be 1-3)
131 // - Invalid titlevalue (must be 0 or 1-3)
132 // - titlevalue and messagevalue cannot be the same
133 // - Network connectivity issues
134 // - HTTP error status codes from IFTTT (non-2xx responses)
135 // - Invalid URL query parameters
136 //
137 // # Security Considerations
138 //
139 // - Store webhook keys securely - avoid hardcoding them in source code or configuration files
140 // - Webhook keys provide access to trigger your IFTTT applets - treat them as secrets
141 // - Consider using separate webhook keys for different purposes to limit exposure
142 // - IFTTT webhook URLs are person-specific - ensure proper access controls
143 // - Be cautious about what data you send in value fields - they may be logged by IFTTT
144 // - Review IFTTT's data handling and privacy policies
145 // - Consider implementing rate limiting on your side to avoid triggering IFTTT limits
146 // - Message content should not contain sensitive information if not using private applets
147 //
148 // # Limitations and Behaviors
149 //
150 // - At least one event name must be specified
151 // - Webhook ID is required and must be a valid IFTTT webhook key
152 // - messagevalue must be between 1 and 3 (default: 2, which maps to Value2)
153 // - titlevalue must be between 0 and 3 (default: 0, disabled)
154 // - titlevalue and messagevalue cannot use the same value field
155 // - Multiple events can be specified as comma-separated values; all will be triggered
156 // - The HTTP client timeout is the default Go HTTP client timeout
157 // - IFTTT returns HTTP 200 on successful event triggers
158 // - Failed events (non-2xx responses) will return an error with the event name
159 // - When multiple events are specified, the service stops at the first failure
160 // - Value fields accept any string content; IFTTT applets determine how to use them
161 //
162 // # IFTTT Webhook Payload
163 //
164 // The notification is sent as a JSON POST request to IFTTT's webhook endpoint:
165 //
166 // https://maker.ifttt.com/trigger/{event}/with/key/{webhookID}
167 //
168 // The payload contains up to three values:
169 //
170 // {
171 // "value1": "...",
172 // "value2": "...",
173 // "value3": "..."
174 // }
175 //
176 // Your IFTTT applets can then use these values in any way - sending emails, SMS messages,
177 // push notifications, or triggering other actions. For more information about IFTTT webhook
178 // payloads, see the IFTTT documentation.
179 package ifttt