Notifications

Configure global notification endpoints

Notification Management

Manage global notification URLs that can be used across all your watches. changedetection.io uses Apprise for notifications, supporting 80+ notification services.

Notification URL Format

Notification URLs follow the Apprise format:

service://credentials/target

Common Services

Email

mailto://user:[e-mail]

Discord

discord://webhook_id/webhook_token

Slack

slack://tokenA/tokenB/tokenC

Telegram

tgram://bottoken/ChatID

For a complete list of supported services, see the Apprise documentation.

---

Get Notification URLs

GET · endpoint

/api/v1/notifications

Retrieve the list of configured global notification URLs.

Response Fields

notification_urls · array

Array of notification URL strings in Apprise format

Example

cURL

curl -X GET "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY"

{
  "notification_urls": [
    "mailto:[e-mail]",
    "discord://webhook_id/webhook_token",
    "tgram://bottoken/ChatID"
  ]
}

---

Add Notification URLs

POST · endpoint

/api/v1/notifications

Add one or more notification URLs to the global configuration.

Request Body

notification_urls · array · required

Array of notification URLs in Apprise format (max 100 URLs)

Example

cURL

curl -X POST "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_urls": [
      "mailto:[e-mail]",
      "discord://webhook_id/webhook_token"
    ]
  }'

{
  "notification_urls": [
    "mailto:[e-mail]",
    "discord://webhook_id/webhook_token"
  ]
}

Notification URLs are validated using Apprise. Invalid URLs will be rejected with a 400 error.

---

Replace All Notification URLs

PUT · endpoint

/api/v1/notifications

Replace the entire list of notification URLs. This will delete all existing URLs and replace them with the provided list.

Request Body

notification_urls · array · required

Array of notification URLs (can be empty to clear all notifications)

Example

cURL

curl -X PUT "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_urls": [
      "mailto:[e-mail]"
    ]
  }'

{
  "notification_urls": [
    "mailto:[e-mail]"
  ]
}

---

Delete Notification URLs

DELETE · endpoint

/api/v1/notifications

Delete specific notification URLs from the configuration.

Request Body

notification_urls · array · required

Array of notification URLs to delete

Example

cURL

curl -X DELETE "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_urls": [
      "mailto:[e-mail]"
    ]
  }'

If none of the specified URLs exist in the configuration, the API returns a 400 error.

---

Notification URL Validation

All notification URLs are validated before being saved. The validation checks:

• URL format is correct for Apprise
• Service type is supported
• Required credentials are present

Invalid URL Examples

// Missing credentials
"mailto:@gmail.com"  // ❌ Invalid

// Invalid service
"unknownservice://token"  // ❌ Invalid

// Malformed URL
"discord:/webhook_id"  // ❌ Invalid (missing second slash)

// Valid URLs
"mailto:user:[e-mail]"  // ✓ Valid
"discord://webhook_id/webhook_token"  // ✓ Valid

---

Per-Watch vs Global Notifications

You can configure notifications at three levels:

1. Global Notifications

   Set default notifications for all watches via /api/v1/notifications

2. Tag Notifications

   Override global settings for watches in a specific tag

3. Watch Notifications

   Override both global and tag settings for individual watches

Example: Watch-Specific Notifications

import requests

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Create watch with custom notifications
data = {
    'url': 'https://example.com',
    'notification_urls': [
        'mailto:[e-mail]',
        'discord://custom_webhook_id/custom_token'
    ]
}

response = requests.post(
    'http://localhost:5000/api/v1/watch',
    headers=headers,
    json=data
)

---

Supported Notification Services

Email Services

• Gmail: mailto://user:[e-mail]
• Office365: mailto://user:[e-mail]
• Custom SMTP: mailto://user:[e-mail]:587
• Mailgun: mailgun://user@domain/apikey
• SendGrid: sendgrid://apikey:[e-mail]

Chat & Messaging

• Discord: discord://webhook_id/webhook_token
• Slack: slack://tokenA/tokenB/tokenC
• Telegram: tgram://bottoken/ChatID
• Microsoft Teams: msteams://TokenA/TokenB/TokenC
• Mattermost: mmost://hostname/authkey
• Rocket.Chat: rocket://user:password@hostname/#channel

Mobile Push

• Pushover: pover://user@token
• Pushbullet: pbul://accesstoken
• Pushy: pushy://apikey@device
• Gotify: gotify://hostname/token
• Apprise API: apprise://hostname/token

SMS Services

• Twilio: twilio://AccountSid:AuthToken@FromPhoneNo
• Nexmo: nexmo://ApiKey:ApiSecret@FromPhoneNo
• AWS SNS: sns://AccessKeyID/AccessKeySecret/RegionName/+PhoneNo

Other Services

• Webhooks: json://hostname/path or xml://hostname/path
• IFTTT: ifttt://webhooks_key/event_name
• Home Assistant: hassio://hostname/token
• Matrix: matrix://user:token@hostname
• Zulip: zulip://botname@organization/token

For the complete list, see Apprise Supported Notifications.

---

Notification Customization

You can customize notification content per watch:

notification_title · string

Custom title template (supports variables like {{watch_url}}, {{watch_title}})

notification_body · string

Custom body template (supports the same variables)

notification_format · string

Format: text, html, htmlcolor, markdown, or System default

Example with Custom Template

data = {
    'url': 'https://example.com',
    'notification_urls': ['mailto:[e-mail]'],
    'notification_title': 'Change detected on {{watch_title}}',
    'notification_body': 'URL: {{watch_url}}\n\nChanges:\n{{diff}}',
    'notification_format': 'text'
}

---

Testing Notifications

To test a notification URL before adding it:

1. Add it to a watch temporarily
2. Trigger a manual recheck with changes
3. Verify the notification arrives
4. If successful, add to global configuration

Alternatively, use the Apprise CLI to test:

# Install Apprise CLI
pip install apprise

# Test a notification URL
apprise -b "Test message" "discord://webhook_id/webhook_token"