CheddahBot/docs/ntfy-setup.md

ntfy.sh Push Notifications Setup

CheddahBot sends push notifications to your phone and desktop via ntfy.sh when tasks complete, reports are ready, or errors occur.

1. Install the ntfy App

• Android: Play Store
• iOS: App Store
• Desktop: Open ntfy.sh in your browser and enable browser notifications when prompted

2. Pick Topic Names

Topics are like channels. Anyone who knows the topic name can subscribe, so use random strings:

cheddahbot-a8f3k9x2m7
cheddahbot-errors-p4w2j6n8

Generate your own — any random string works. No account or registration needed.

3. Subscribe to Your Topics

Phone app:

1. Open the ntfy app
2. Tap the + button
3. Enter your topic name (e.g. cheddahbot-a8f3k9x2m7)
4. Server: https://ntfy.sh (default)
5. Repeat for your errors topic

Browser:

1. Go to ntfy.sh
2. Click "Subscribe to topic"
3. Enter the same topic names
4. Allow browser notifications when prompted

4. Add Topics to .env

Add these lines to your .env file in the CheddahBot root:

NTFY_TOPIC_HUMAN_ACTION=cheddahbot-a8f3k9x2m7
NTFY_TOPIC_ERRORS=cheddahbot-errors-p4w2j6n8

Replace with your actual topic names.

5. Restart CheddahBot

Kill the running instance and restart:

uv run python -m cheddahbot

You should see in the startup logs:

ntfy notifier initialized with 2 channel(s): human_action, errors
ntfy notifier subscribed to notification bus

What Gets Notified

human_action channel (high priority)

Notifications where you need to do something:

• Cora report finished and ready
• Press release completed
• Content outline ready for review
• Content optimization completed
• Link building pipeline finished
• Cora report distributed to inbox

errors channel (urgent priority)

Notifications when something went wrong:

• ClickUp task failed or was skipped
• AutoCora job failed
• Link building pipeline error
• Content pipeline error
• Missing ClickUp field matches
• File copy failures

Configuration

Channel routing is configured in config.yaml under the ntfy: section. Each channel has:

• topic_env_var — which env var holds the topic name
• categories — notification categories to listen to (clickup, autocora, linkbuilding, content)
• include_patterns — regex patterns the message must match (at least one)
• exclude_patterns — regex patterns that reject the message (takes priority over include)
• priority — ntfy priority level: min, low, default, high, urgent
• tags — emoji shortcodes shown on the notification (e.g. white_check_mark, rotating_light)

Adding a New Channel

1. Add a new entry under ntfy.channels in config.yaml
2. Add the topic env var to .env
3. Subscribe to the topic in your ntfy app
4. Restart CheddahBot

Privacy

The public ntfy.sh server has no authentication by default. Your topic name is the only security — use a long random string to make it unguessable. Alternatively:

• Create a free ntfy.sh account and set read/write ACLs on your topics
• Self-host ntfy (single binary) and set server: http://localhost:8080 in config.yaml

Disabling

Set enabled: false in the ntfy: section of config.yaml, or remove the env vars from .env.