Skip to content

Webhooks

Get notified when a sync completes or fails. The webhook sends a POST request with sync results to any URL you configure.

Discord is the only tested provider, but any endpoint that accepts JSON POST requests should work (Slack, ntfy, custom servers, etc.).

Configuration

Docker: Open Settings and scroll to the Webhooks section. Enter your webhook URL, choose when to send notifications, and use the Test button to verify.

CLI: Add to your .env:

WEBHOOK_URL=https://discord.com/api/webhooks/123456/abcdef
WEBHOOK_EVENTS=all    # "all" = success + error, "error" = failures only
Variable Default Description
WEBHOOK_URL (empty) Webhook endpoint URL. Leave empty to disable.
WEBHOOK_EVENTS error When to send: all (every sync) or error (failures only)

Payload

Each webhook payload includes:

  • Status - success or error
  • Sync type - main or tags
  • Timestamp - ISO 8601 timestamp of the sync
  • Tracks resolved / missed / total
  • Duration - wall-clock sync time in seconds
  • Cache hits / misses - with hit rate percentage
  • API searches - number of YouTube Music queries made
  • Playlist link (on success)
  • Error details (on failure, truncated to 500 characters)

Discord Format

Discord webhooks are auto-detected by URL (matching discord.com/api/webhooks/ or discordapp.com/api/webhooks/) and formatted as rich embeds with color-coded status:

  • 🟢 Green for success
  • 🔴 Red for errors

Other endpoints receive a plain JSON object with the same fields. Error details in Discord embeds are truncated to 1000 characters.