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:[email protected]

Discord

discord://webhook_id/webhook_token

Slack

slack://tokenA/tokenB/tokenC

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 -X GET "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY"

{
  "notification_urls": [
    "mailto:[email protected]",
    "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 -X POST "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_urls": [
      "mailto:[email protected]",
      "discord://webhook_id/webhook_token"
    ]
  }'

{
  "notification_urls": [
    "mailto:[email protected]",
    "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 -X PUT "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_urls": [
      "mailto:[email protected]"
    ]
  }'

{
  "notification_urls": [
    "mailto:[email protected]"
  ]
}

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 -X DELETE "http://localhost:5000/api/v1/notifications" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_urls": [
      "mailto:[email protected]"
    ]
  }'

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:[email protected]"  // ✓ Valid
"discord://webhook_id/webhook_token"  // ✓ Valid

Per-Watch vs Global Notifications

You can configure notifications at three levels:

Global Notifications

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

Tag Notifications

Override global settings for watches in a specific tag

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:[email protected]',
        '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:[email protected]
Office365: mailto://user:[email protected]
Custom SMTP: mailto://user:[email protected]:587
Mailgun: mailgun://user@domain/apikey
SendGrid: sendgrid://apikey:[email protected]

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:[email protected]'],
    '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:

Add it to a watch temporarily
Trigger a manual recheck with changes
Verify the notification arrives
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"

Overview

Endpoints

Notifications

Notification Management

Notification URL Format

Common Services

Email

Discord

Slack

Telegram

Get Notification URLs

Response Fields

Example

Add Notification URLs

Request Body

Example

Replace All Notification URLs

Request Body

Example

Delete Notification URLs

Request Body

Example

Notification URL Validation

Invalid URL Examples

Per-Watch vs Global Notifications

Example: Watch-Specific Notifications

Supported Notification Services

Notification Customization

Example with Custom Template

Testing Notifications

Build docs developers (and LLMs) love

Overview

Endpoints

​Notification Management

​Notification URL Format

​Common Services

Email

Discord

Slack

Telegram

​Get Notification URLs

​Response Fields

​Example

​Add Notification URLs

​Request Body

​Example

​Replace All Notification URLs

​Request Body

​Example

​Delete Notification URLs

​Request Body

​Example

​Notification URL Validation

​Invalid URL Examples

​Per-Watch vs Global Notifications

​Example: Watch-Specific Notifications

​Supported Notification Services

​Notification Customization

​Example with Custom Template

​Testing Notifications

Build docs developers (and LLMs) love

Notification Management

Notification URL Format

Common Services

Get Notification URLs

Response Fields

Example

Add Notification URLs

Request Body

Example

Replace All Notification URLs

Request Body

Example

Delete Notification URLs

Request Body

Example

Notification URL Validation

Invalid URL Examples

Per-Watch vs Global Notifications

Example: Watch-Specific Notifications

Supported Notification Services

Notification Customization

Example with Custom Template

Testing Notifications