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