webhook-notify

name

webhook-notify

description

Set up webhook-to-desktop notification systems using Cloudflare Workers and ntfy.sh. Use when users want to receive desktop notifications for webhooks from services like Stripe payments, GitHub events, custom app alerts, error monitoring, or any webhook source. Handles the full setup including worker deployment, local listener, and background service installation. Supports custom sounds, click actions, rich content, and event filtering.

Webhook Desktop Notifications

Set up secure, reliable webhook-to-desktop notification systems that receive webhooks from any source and display native desktop notifications on macOS.

Architecture

The system uses a proven pattern:

1. Cloudflare Worker - Receives webhooks from external services (Stripe, GitHub, custom apps)
2. ntfy.sh - Message relay service (no account required)
3. Local Listener - Background process that subscribes to ntfy.sh and displays desktop notifications
4. macOS Service - Keeps listener running automatically

Benefits:

• No local port exposure or tunneling required
• Secure and reliable message delivery
• Free tier sufficient for most use cases
• Handles network interruptions with automatic reconnection

Quick Start

Run the init script to set up a new webhook notification system:

scripts/init_webhook.sh <webhook-name> <ntfy-topic> [output-dir] [sound-file]

Example:

scripts/init_webhook.sh stripe-payments myapp-stripe

This creates:

• Cloudflare Worker for receiving webhooks
• Local listener script for desktop notifications
• macOS launchd service configuration
• All necessary configuration files

Workflow

Step 1: Initialize Webhook System

Run init_webhook.sh with appropriate parameters:

Arguments:

• webhook-name: Identifier for this webhook (e.g., "stripe-payments", "github-prs")
• ntfy-topic: Your unique ntfy.sh topic name (e.g., "myapp-notifications-2024")
• output-dir: (Optional) Where to create files (default: ~/.claude/webhooks/<webhook-name>)
• sound-file: (Optional) Custom notification sound (default: system sound)

Example with custom sound:

scripts/init_webhook.sh github-alerts my-github-topic ~/webhooks /path/to/alert.mp3

Step 2: Customize Worker Logic

Edit the generated worker.js to handle your specific webhook format.

The worker template includes examples for:

• Generic webhooks (title/message/url format)
• Stripe payment events
• GitHub events (PRs, issues, releases)

Modify the extractNotification() function to parse your webhook structure and return notification details.

Example for custom app webhooks:

function extractNotification(event) {
  // Your custom webhook format
  if (event.type === 'user.signup') {
    return {
      title: 'New User Signup',
      message: `${event.user_email} just created an account`,
      priority: '4',
      tags: 'user,tada',
      url: `https://myapp.com/admin/users/${event.user_id}`,
    };
  }

  return null; // Ignore other events
}

Notification object fields:

• title: Notification title (required)
• message: Notification body text (required)
• priority: 1-5, where 5 is highest (optional, default: 3)
• tags: Emoji tags for ntfy.sh like "moneybag", "warning", "fire" (optional)
• url: URL to open when notification is clicked (optional)

For common patterns, see EXAMPLES.md with complete examples for:

• Stripe payments and refunds
• GitHub PR/issue notifications
• Error monitoring and alerts
• Custom business events
• Event filtering and routing

Step 3: Deploy Cloudflare Worker

Navigate to the webhook directory and deploy:

cd ~/.claude/webhooks/<webhook-name>/webhook
npx wrangler deploy

The deployment will output your worker URL:

https://<webhook-name>.<your-subdomain>.workers.dev

Configure your webhook source to send POST requests to:

https://<webhook-name>.<your-subdomain>.workers.dev/webhook

Optional: Add webhook secret for signature verification:

npx wrangler secret put WEBHOOK_SECRET

Step 4: Install Local Listener

Install the listener as a background service that starts automatically:

scripts/install_service.sh ~/.claude/webhooks/<webhook-name>/com.webhook.<webhook-name>.plist

The service will:

• Start immediately
• Restart automatically if it crashes
• Run on system startup

Test manually before installing:

~/.claude/webhooks/<webhook-name>/listener.sh

Then send a test notification:

curl -d 'Test notification!' https://ntfy.sh/<your-topic>

Step 5: Test End-to-End

Send a test webhook to verify the complete flow:

curl -X POST https://<webhook-name>.<your-subdomain>.workers.dev/webhook \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","message":"Hello from webhook!"}'

You should see:

1. Worker logs in Cloudflare dashboard
2. Message in listener logs: ~/.claude/webhooks/<webhook-name>/logs/listener.log
3. Desktop notification with sound

Troubleshooting

No notification received:

1. Check worker logs: cd webhook && npx wrangler tail
2. Check listener logs: tail -f ~/.claude/webhooks/<webhook-name>/logs/*.log
3. Verify service is running: launchctl list | grep webhook
4. Test ntfy.sh directly: curl -d "Test" https://ntfy.sh/<your-topic>

Notification sound not playing:

• Verify sound file exists and is valid audio format
• Check macOS notification permissions for terminal-notifier
• Try with default system sound first

Service keeps stopping:

• Check stderr log: cat ~/.claude/webhooks/<webhook-name>/logs/stderr.log
• Ensure terminal-notifier is installed: brew install terminal-notifier
• Verify listener script has execute permissions

Too many notifications (keepalive messages):

• The listener template already filters empty keepalive messages
• If still seeing duplicates, check worker extractNotification() logic

Common Patterns

Multiple Webhooks

Create separate notification systems for different sources:

scripts/init_webhook.sh stripe-payments myapp-stripe
scripts/init_webhook.sh github-alerts myapp-github
scripts/init_webhook.sh error-monitoring myapp-errors

Each runs independently with its own worker, listener, and service.

Event Filtering

Return null from extractNotification() to ignore events:

function extractNotification(event) {
  // Ignore test events
  if (event.test || event.environment !== 'production') {
    return null;
  }

  // Ignore low-priority actions
  if (event.action === 'labeled') {
    return null;
  }

  // Handle other events...
}

Priority-Based Sounds

Modify listener.sh to play different sounds by priority:

priority=$(echo "$message" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('priority','3'))" 2>/dev/null || echo "3")

if [[ "$priority" == "5" ]]; then
    afplay "/System/Library/Sounds/Sosumi.aiff" &  # Critical
elif [[ "$priority" == "4" ]]; then
    afplay "$CUSTOM_SOUND" &  # High priority
fi

Rich Notifications

ntfy.sh supports image attachments and action buttons:

await fetch(NTFY_URL, {
  method: 'POST',
  headers: {
    'Title': notification.title,
    'Attach': 'https://example.com/screenshot.png',
    'Actions': 'view, View details, https://example.com',
  },
  body: notification.message,
});

Managing Services

Check if service is running:

launchctl list | grep com.webhook.<webhook-name>

View live logs:

tail -f ~/.claude/webhooks/<webhook-name>/logs/*.log

Restart service:

launchctl unload ~/Library/LaunchAgents/com.webhook.<webhook-name>.plist
launchctl load ~/Library/LaunchAgents/com.webhook.<webhook-name>.plist

Stop service:

launchctl unload ~/Library/LaunchAgents/com.webhook.<webhook-name>.plist

Uninstall completely:

launchctl unload ~/Library/LaunchAgents/com.webhook.<webhook-name>.plist
rm ~/Library/LaunchAgents/com.webhook.<webhook-name>.plist
rm -rf ~/.claude/webhooks/<webhook-name>

Resources

scripts/

• init_webhook.sh - Initialize new webhook notification system
• install_service.sh - Install listener as macOS background service

assets/

• worker-template.js - Cloudflare Worker template
• listener-template.sh - Local listener script template
• launchd-template.plist - macOS service configuration template

references/

• EXAMPLES.md - Complete examples for common webhook sources (Stripe, GitHub, error monitoring, custom apps) with code samples and patterns