Notifications

Get instant notifications when domains are blocked, unblocked, or when special modes are activated. NextDNS Blocker supports multiple notification channels with batching and async delivery.

Supported Channels

Channel	Description
Discord	Webhook notifications with rich embeds
Telegram	Bot notifications via Telegram API
Slack	Webhook notifications with Block Kit
Ntfy	Simple push notifications via ntfy.sh
macOS	Native system notifications via osascript

Configuration

Notifications are configured in config.json under the notifications section:

{
  "notifications": {
    "enabled": true,
    "channels": {
      "discord": {
        "enabled": true,
        "webhook_url": "https://discord.com/api/webhooks/1234567890/abcdefghijklmnop"
      },
      "telegram": {
        "enabled": true,
        "bot_token": "123456:ABC-DEF...",
        "chat_id": "123456789"
      },
      "slack": {
        "enabled": true,
        "webhook_url": "https://hooks.slack.com/services/..."
      },
      "ntfy": {
        "enabled": true,
        "topic": "my-nextdns-alerts"
      },
      "macos": {
        "enabled": true,
        "sound": true
      }
    }
  }
}

Global Settings

Field	Type	Default	Description
`enabled`	boolean	`true`	Master switch for all notifications
`channels`	object	`{}`	Channel-specific configurations

Discord Channel

{
  "discord": {
    "enabled": true,
    "webhook_url": "https://discord.com/api/webhooks/..."
  }
}

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable Discord notifications
`webhook_url`	string	Yes	Full Discord webhook URL

Creating a Discord Webhook:

Open Discord server settings
Go to Integrations > Webhooks
Click New Webhook
Name it (e.g., “NextDNS Blocker”)
Select the channel for notifications
Click Copy Webhook URL

Telegram Channel

{
  "telegram": {
    "enabled": true,
    "bot_token": "123456:ABC-DEF...",
    "chat_id": "123456789"
  }
}

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable Telegram notifications
`bot_token`	string	Yes	Telegram Bot API Token
`chat_id`	string	Yes	Target Chat ID (user or group)

Setup:

Chat with @BotFather to create a bot and get bot_token
Chat with @userinfobot to get your chat_id

Slack Channel

{
  "slack": {
    "enabled": true,
    "webhook_url": "https://hooks.slack.com/services/..."
  }
}

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable Slack notifications
`webhook_url`	string	Yes	Slack Incoming Webhook URL

Setup:

Create an Incoming Webhook in your Slack workspace
Copy the Webhook URL

Ntfy Channel

{
  "ntfy": {
    "enabled": true,
    "topic": "my-nextdns-alerts",
    "server": "https://ntfy.sh"
  }
}

Field	Type	Default	Description
`enabled`	boolean	No	Enable Ntfy notifications
`topic`	string	Required	Topic name to subscribe to
`server`	string	`https://ntfy.sh`	Optional self-hosted server URL

macOS Channel

{
  "macos": {
    "enabled": true,
    "sound": true
  }
}

Field	Type	Default	Description
`enabled`	boolean	No	Enable macOS native notifications
`sound`	boolean	`true`	Play sound with notification

Note: macOS notifications only work when running on macOS. The channel is automatically disabled on other platforms.

Notification Types

Sync Complete (Batched)

After each sync, a summary notification is sent:

Discord Example:

:bar_chart: NextDNS Blocker Sync Complete

:red_circle: Blocked (3): reddit.com, twitter.com, instagram.com
:green_circle: Unblocked (1): github.com
:shield: PC Activated (2): gambling, tiktok
:clock3: Scheduled (1): bumble.com

Profile: abc123 | Synced at 14:30

macOS Example:

NextDNS Blocker Sync
Blocked: 3 | Unblocked: 1 | Allowed: 0

Event Types

Event	Icon	Color	Description
Block	:red_circle:	Red	Domain added to denylist
Unblock	:green_circle:	Green	Domain removed from denylist
Allow	:white_check_mark:	Green	Domain added to allowlist
Disallow	:x:	Orange	Domain removed from allowlist
PC Activate	:shield:	Blue	Parental Control category/service activated
PC Deactivate	:unlock:	Blue	Parental Control category/service deactivated
Pending	:clock3:	Yellow	Unblock scheduled with delay
Panic	:rotating_light:	Dark Red	Panic mode activated
Error	:warning:	Red	Operation failed

Features

Batching

Instead of sending individual notifications for each domain change, events are collected during a sync operation and sent as a single notification:

Reduces notification spam
Provides a summary view
Groups events by type

Async Delivery

Notifications are sent asynchronously in a background thread:

Sync operations don’t wait for notification delivery
Notification failures don’t affect sync success
Multiple adapters can send in parallel

Rate Limiting

Discord webhooks have rate limits. NextDNS Blocker handles this by:

Batching events to reduce API calls
Logging rate limit errors without retrying

Testing

Verify your notification setup:

nextdns-blocker test-notifications

This sends a test message to all configured and enabled channels.

Complete Configuration Example

{
  "version": "1.0",
  "settings": {
    "timezone": "America/New_York"
  },
  "notifications": {
    "enabled": true,
    "channels": {
      "discord": {
        "enabled": true,
        "webhook_url": "https://discord.com/api/webhooks/123456789/abcdef..."
      },
      "macos": {
        "enabled": true,
        "sound": true
      }
    }
  },
  "blocklist": [...]
}

Disabling Notifications

Disable All Notifications

{
  "notifications": {
    "enabled": false
  }
}

Disable Specific Channel

{
  "notifications": {
    "enabled": true,
    "channels": {
      "discord": {
        "enabled": false,
        "webhook_url": "..."
      }
    }
  }
}

Remove Configuration

Simply remove the notifications section from config.json.

Troubleshooting

Discord notifications not appearing

Check webhook URL:
- Verify URL starts with https://discord.com/api/webhooks/
- Copy fresh from Discord settings
Check configuration:
Terminal window
```
nextdns-blocker config show
```
Look for the notifications section.

Test webhook manually:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"content": "Test from NextDNS Blocker"}' \
  "YOUR_WEBHOOK_URL"

Check logs:

tail -20 ~/.local/share/nextdns-blocker/logs/cron.log

macOS notifications not appearing

Check System Preferences:
- Go to System Preferences > Notifications
- Ensure notifications are allowed for Terminal/iTerm
Check platform:
- macOS notifications only work on macOS
- The channel is auto-disabled on other platforms

Webhook invalid or expired

Recreate webhook in Discord
Update config.json with new URL
Test with nextdns-blocker test-notifications

Privacy Considerations

What’s Shared

Notifications include:

Domain names being blocked/unblocked
Category/service names (Parental Control)
Timestamps
Action types

What’s NOT Shared

Notifications don’t include:

Your IP address
NextDNS credentials
Full configuration details

Recommendations

Use a private Discord server
Don’t share webhook URLs
Consider a dedicated notification channel
Review channel access permissions

Channel Ideas

Separate Channels

Create different webhooks for different purposes:

#nextdns-alerts - All sync notifications
#nextdns-panic - Only panic mode (urgent)
#accountability - Share with accountability partner

Private vs Shared

Private channel: Personal monitoring
Shared channel: Accountability with trusted person