How to Use Plex Webhooks for Automation

Published September 1, 2026 · 10 min read

Plex webhooks let your server notify external services whenever something happens — a movie starts playing, a new episode is added to the library, or someone pauses a stream. This opens up powerful automation possibilities: dim the lights when movie night starts, send a Discord notification when new content arrives, or log every play to a spreadsheet. This guide explains how webhooks work, what data they send, and how to connect them to popular automation platforms.

What Are Webhooks?

A webhook is a URL that Plex sends an HTTP POST request to whenever a specific event occurs on your server. Think of it as a push notification for machines. Instead of polling Plex repeatedly to ask "did anything happen?" your automation tool simply waits for Plex to call its URL with event data.

When an event fires, Plex sends a JSON payload containing details about what happened, which user triggered it, and what media was involved. Your receiving service parses this payload and takes action based on the event type and data.

Plex Pass Requirement

Webhooks are a Plex Pass feature. You need an active Plex Pass subscription (monthly, yearly, or lifetime) to configure webhook URLs in your server settings. Without Plex Pass, the webhooks section does not appear in settings. Third-party tools like Tautulli can provide webhook-like functionality without Plex Pass, but native Plex webhooks are the simplest and most reliable option.

Setting Up Your First Webhook

Step 1 — Get a Receiving URL

You need a URL that can receive HTTP POST requests. Options include:

• Webhook.site: A free testing tool that displays incoming webhook payloads in real time. Great for understanding the data format before building real integrations.
• A local script: A simple Python Flask or Node.js Express server running on your network.
• Home Assistant: Has a built-in webhook trigger for automations.
• Zapier or Make (formerly Integromat): Cloud automation platforms with webhook receivers.
• n8n: Self-hosted automation platform with a webhook node.

Step 2 — Add the URL in Plex

Open the Plex web interface, go to Settings, then Webhooks (under your server name, not account settings). Click "Add Webhook" and paste your receiving URL. Click Save. Plex will now send event data to this URL whenever qualifying events occur. You can add multiple webhook URLs if you want different services to receive the same events.

Step 3 — Trigger a Test Event

Play any media on any client connected to your server, then pause and stop it. Each action generates a webhook event. Check your receiving service to confirm the payloads arrived. If nothing appears, verify that your URL is accessible from your Plex server's network and that any firewalls allow outbound HTTP traffic from the server.

Event Types

Plex sends webhooks for the following events:

• media.play: Playback starts on any client.
• media.pause: Playback is paused.
• media.resume: Playback resumes after a pause.
• media.stop: Playback stops completely.
• media.scrobble: A media item has been watched past the scrobble threshold (typically around 90% for movies and episodes).
• media.rate: A user rates a media item.
• library.on.deck: A new item appears on a user's On Deck.
• library.new: A new item is added to a library.
• admin.database.backup: A database backup completes.
• admin.database.corrupted: Database corruption is detected.
• device.new: A new device connects to the server.
• playback.started: Similar to media.play but includes transcoding details.

Payload Structure

Each webhook POST contains a multipart form with a JSON payload in the payload field. The JSON structure includes:

{
  "event": "media.play",
  "user": true,
  "owner": true,
  "Account": {
    "id": 12345,
    "title": "YourUsername",
    "thumb": "https://plex.tv/users/..."
  },
  "Server": {
    "title": "My Plex Server",
    "uuid": "abc123..."
  },
  "Player": {
    "local": true,
    "publicAddress": "192.168.1.100",
    "title": "Living Room TV",
    "uuid": "def456..."
  },
  "Metadata": {
    "type": "movie",
    "title": "The Matrix",
    "year": 1999,
    "thumb": "/library/metadata/123/thumb",
    "grandparentTitle": "",
    "parentTitle": "",
    "summary": "A computer hacker learns..."
  }
}

The Metadata object varies by media type. For TV episodes, grandparentTitle contains the show name and parentTitle contains the season name. For music, the hierarchy maps to artist, album, and track.

Integration Examples

Home Assistant — Dim Lights on Play

Home Assistant supports webhooks as automation triggers natively. In your Home Assistant automations.yaml, create a webhook trigger:

automation:
  - alias: "Dim lights when Plex plays"
    trigger:
      - platform: webhook
        webhook_id: plex-play-event
        local_only: true
    condition:
      - condition: template
        value_template: "{{ trigger.json.event == 'media.play' }}"
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness_pct: 10

Add the webhook URL http://YOUR-HA-IP:8123/api/webhook/plex-play-event to your Plex webhook settings. When playback starts, Home Assistant dims the living room lights to 10%. Add a second automation that restores brightness on media.stop.

Discord Notifications

Discord channels support incoming webhooks natively. Create a webhook in your Discord channel settings (Edit Channel, Integrations, Webhooks, New Webhook). However, Plex's webhook payload format does not match Discord's expected format, so you need a translation layer.

Options for this include Tautulli (which has built-in Discord notification support), a simple middleware script, or a cloud automation service like n8n that receives the Plex webhook, reformats the data, and sends a formatted Discord message with the media title, thumbnail, and user who started playback.

Scrobbling to Trakt.tv

The media.scrobble event fires when you finish watching something. Use this to sync your watch history to Trakt.tv. While dedicated tools like PlexTraktSync are more robust for this specific use case, a webhook-based approach gives you more control. Forward the scrobble event to a script that calls the Trakt.tv API with the TMDB or TVDB ID from the Plex metadata.

Logging Plays to a Spreadsheet

Use Zapier or Make to receive Plex webhooks and append a row to a Google Sheet for every media.play event. Log the title, user, timestamp, and player device. Over time, this creates a detailed viewing history you can analyze. Useful for families who want to track screen time or for server admins who want usage insights without installing Tautulli.

Troubleshooting Webhooks

• No events arriving: Verify your Plex Pass is active. Check that the URL is correct and reachable from the server. Test the URL manually with curl -X POST your-url.
• Events arriving inconsistently: Some events fire only for the server owner, not for shared users. The user and owner fields in the payload indicate who triggered the event.
• Duplicate events: Some actions generate multiple events in rapid succession (e.g., stop immediately followed by scrobble). Build debounce logic into your receiving script if this causes problems.
• Payload too large: If your receiving service rejects the POST, it may have a body size limit. Plex webhook payloads can include base64-encoded thumbnail data that inflates the size. Configure your receiver to accept larger payloads or ignore the thumbnail field.

Security Considerations

Plex webhooks do not include a signature or shared secret for verifying authenticity. If your webhook URL is exposed to the internet, anyone who discovers it could send fake events. Mitigations include: keeping your webhook receivers on your local network only, using a randomized URL path that is hard to guess, checking the source IP against your Plex server's address, and validating that the payload structure matches Plex's format before acting on it.