4.0 KiB
Jellyseerr Webhook Setup Guide
This guide will help you set up instant notifications from Jellyseerr using webhooks instead of polling.
Benefits
- Instant notifications - Get notified immediately when media becomes available
- Lower API usage - No need to poll every few minutes
- More reliable - Direct push notifications from Jellyseerr
Step 1: Install the Webhook Server
Run the setup script to create a systemd service:
cd /home/bot/bot/skills/jellyseerr
./scripts/setup_webhook.sh 8384
This will:
- Create a systemd service running on port 8384
- Start the service automatically
- Configure it to restart on failure
Step 2: Configure Jellyseerr
Get Your Server IP
hostname -I | awk '{print $1}'
Configure Webhook in Jellyseerr
- Open Jellyseerr web interface
- Go to Settings → Notifications → Webhook
- Click Enable toggle
- Set Webhook URL to:
http://YOUR_IP:8384/(Replace YOUR_IP with your server's IP address)
Set JSON Payload Template
In the JSON Payload field, use this base64-encoded template:
eyJub3RpZmljYXRpb25fdHlwZSI6Int7bm90aWZpY2F0aW9uX3R5cGV9fSIsInN1YmplY3QiOiJ7e3N1YmplY3R9fSIsIm1lc3NhZ2UiOiJ7e21lc3NhZ2V9fSIsIm1lZGlhX3R5cGUiOiJ7e21lZGlhX3R5cGV9fSIsIm1lZGlhX3RtZGJpZCI6Int7bWVkaWFfdG1kYmlkfX0ifQ==
This decodes to:
{
"notification_type": "{{notification_type}}",
"subject": "{{subject}}",
"message": "{{message}}",
"media_type": "{{media_type}}",
"media_tmdbid": "{{media_tmdbid}}"
}
Enable Notification Types
Under Notification Types, enable:
- ✅ Media Available
You can optionally enable other types if you want notifications for:
- Media Requested
- Media Approved
- Media Failed
- etc.
Test and Save
- Click Test button to send a test notification
- Check the webhook server logs:
sudo journalctl -u jellyseerr-webhook -f - If successful, click Save Changes
Step 3: Configure Telegram Chat ID (Optional)
If not already configured, add your Telegram chat ID to the config:
config_file="$HOME/.config/jellyseerr/config.json"
jq '. + {"telegram_chat_id": "YOUR_CHAT_ID"}' "$config_file" > "$config_file.tmp" && mv "$config_file.tmp" "$config_file"
Or set it as an environment variable:
export TELEGRAM_CHAT_ID="YOUR_CHAT_ID"
Verification
Check Service Status
sudo systemctl status jellyseerr-webhook
View Live Logs
sudo journalctl -u jellyseerr-webhook -f
Test a Request
- Request a movie in Jellyseerr
- Watch the webhook logs
- When it becomes available, you should see:
- Webhook received in logs
- Notification queued
- Message sent to Telegram (on next heartbeat or immediately if you trigger it)
Troubleshooting
Service won't start
Check logs:
sudo journalctl -u jellyseerr-webhook -n 50
Webhook not receiving requests
-
Verify firewall allows port 8384:
sudo ufw allow 8384/tcp -
Test locally:
curl -X POST http://localhost:8384/ \ -H "Content-Type: application/json" \ -d '{"notification_type":"TEST","subject":"Test Movie"}'
Notifications not being sent
Check if notifications are queued:
cat ~/.cache/jellyseerr/pending_notifications.json
If they exist but aren't being sent, trigger a manual send or wait for the next heartbeat.
Maintenance
Restart Service
sudo systemctl restart jellyseerr-webhook
Stop Service
sudo systemctl stop jellyseerr-webhook
Uninstall Service
sudo systemctl stop jellyseerr-webhook
sudo systemctl disable jellyseerr-webhook
sudo rm /etc/systemd/system/jellyseerr-webhook.service
sudo systemctl daemon-reload
Migration from Polling
If you were using the old polling method:
-
Remove cron job (if any):
crontab -l | grep -v jellyseerr | crontab - -
Clear HEARTBEAT.md (it's now just comments)
-
Set up webhook as described above
The new system is more efficient and provides instant notifications!