Get a notification when media is added to Plex – Tautulli + Home Assistant via webhooks

Recently, after playing with similar projects using Home Assistant, I thought it would be useful to set something up where I received mobile notifications (ideally sms) if any episodes of particular shows were added to Plex. I found that the Plex mobile app provides similar features and uses push notifications. However, I wanted to use Home Assistant so I could have the ability to later tie in whatever automation trigger I wanted based on Plex events (not just notifications). I finally ended up using Tautulli (as a webhook “broker”) to handle triggering the webhook which I configured in Home Assistant, which in turn triggers the automation finally sending me a notification via text message. A solution that can be used for any Plex webhook event.

I originally figured I could utilize the Plex “sensor” or “component” features that are available to Home Assistant, but those items seem to deal more with creating automations based on Plex user activity versus things like “recently updated” library activity. Moving on from that, I hadn’t messed with Plex webhooks yet but figured that that would be the endpoint I needed to hook into and grab the data required to shoot me a text of recently added content. I tried this out, but the data I was receiving through this webhook from Plex was pretty dense. I realized that Tautulli ties into Plex webhooks and has a whole system set up for notifications that is insanely feature-rich and too awesome not to take advantage of. There is also a webhooks feature where you can narrow in on what triggers you want (“recently added” in my case), and what JSON data you want to send to Home Assistant. Not bad!

1) Setting up Tautulli to POST JSON “recently added” data to a webhook.

If you’re unfamiliar with Tautulli, here is what their website says: “Tautulli is a 3rd party application that you can run alongside your Plex Media Server to monitor activity and track various statistics.” Also, it can trigger other webhooks based on webhooks triggered by Plex events (what we’re using it for in this post).

Here are some screenshots illustrating the process of setting up a webhook pointing at Home Assistant on port 8123, to POST a small amount of predefined JSON telling Home Assistant the title of the recently added media:

Tautulli – Webhook Settings – Configuration
Tautulli – Webhook Settings – Configuration
Tautulli – Webhook Settings – Configuration

I kept the JSON simple:

{
    "title": "{title}"
}

In the JSON portion above, you can add more values to have Home Assistant send out a more verbose notification. Note: Not seen pictured in the settings window above in Tautulli are links providing more info on the various available JSON values.

Add conditions to only be notified about certain recently added media.

In the above Tautulli settings panel, you can navigate to the “Conditions” tab, and create conditions like the following:

Tautulli – Webhook Settings – Conditional filters

The above condition only triggers the webhook if the recently added episode “title” contains the words, “Elementary” or “Ray Donovan” in this example. This is a great feature, especially for setting this up for other Plex users who do not want to receive info on everything that is added.

That’s pretty much it for Tautulli.

2) Set up Home Assistant to listen to the webhook and trigger notifications.

The next step is to set up HA (Home Assistant) with an “automation” to listen to our webhook and trigger a notification – in this case, a text message using the JSON data POST-ed from Tautulli. In order to achieve this we will need to add an “smtp” email client to our configuration.yaml , and add the automation for triggering the text message via email – more on this below.

Here is the configuration snippet for the smtp email info:

notify:
  - name: sms_over_email
    platform: smtp
    server: smtp.gmail.com
    port: 587
    timeout: 15
    sender: [email protected]
    encryption: starttls
    username: [email protected]
    password: !secret smtp_pass 
    recipient:
      - [email protected] # me
    sender_name: My Home Assistant

The configuration is pretty straightforward here. In regard to setting up your email, there are some guides out there stepping you through the process of enabling the “smtp” service in your email account (if the option is available). I suggest you set up a new email account with smtp enabled, reserved only for these sorts of projects.

How does it send a text through email? Apparently, most mobile providers offer an email -> text feature if you send an email to the [email protected] carriers reserved domain for this purpose.

For Sprint, it is:

For T-Mobile, it is:

For AT&T it should be

Where the x’s become your mobile digits

No need to hand over more data to another 3rd party service just to handle notifications. Just write an email and address it using the schema above and it will convert it to a text for the recipient.

Now, for the automation portion:

- alias: Plex Recently Added Webhook
  trigger:
    platform: webhook
    webhook_id: recently_added # http://<your-ip>:8123/api/webhook/recently_added
  action:
    - service: notify.sms_over_email
      data_template:
        title: 'New Item Added to Plex:'
        message: '{{trigger.json["title"]}}'

This tells Home Assistant to listen to the webhook ID of “recently_added” which is triggered by Tautulli at “http://your-home-assistant-ip:8123/api/webhook/recently_added” (no auth necessary for this). It then triggers an “action” of “notify.sms_over_email” – which sends an email message body of, ‘{{trigger.json[“title”]}}’ to your mobile number.

In the case you add a large amount of media to Plex at once, you’ll be overloaded with text messages (and your email provider might temporarily suspend your email account for spam – beware). To avoid this, I’ve added a condition so that the “automation” can only be triggered once every 60 seconds:

automation:
- alias: Plex Recently Added Webhook
  trigger:
    platform: webhook
    webhook_id: recently_added # http://<your-ip>:8123/api/webhook/recently_added
  condition:
    - condition: template
      value_template: '{{ as_timestamp(now()) - as_timestamp(states.automation.plex_recently_added_webhook.attributes.last_triggered) | int > 60 }}'  
  action:
    - service: notify.sms_over_email
      data_template:
        title: 'New Item Added to Plex:'
        message: '{{trigger.json["title"]}}'

I suggest creating a new email strictly for this purpose (I use gmail). That way if anything goes wrong and your email is temporarily suspended for suspicious activity (happened to me once and lasted 24 hours), you can just wait it out and it won’t really matter.

Here is the full “configuration.yaml” with all the additions:


# Configure a default setup of Home Assistant (frontend, api, etc)
default_config:

# Uncomment this if you are using SSL/TLS, running in Docker container, etc.
# http:
#   base_url: example.duckdns.org:8123

# Text to speech
tts:
  - platform: google_translate

group: !include groups.yaml
script: !include scripts.yaml

notify:
  - name: sms_over_email
    platform: smtp
    server: smtp.gmail.com
    port: 587
    timeout: 15
    sender: [email protected]
    encryption: starttls
    username: [email protected]
    password: !secret smtp_pass 
    recipient:
      - [email protected] # me
    sender_name: My Home Assistant

automation:
- alias: Plex Recently Added Webhook
  trigger:
    platform: webhook
    webhook_id: recently_added # http://<your-ip>:8123/api/webhook/recently_added
  condition:
    - condition: template
      value_template: '{{ as_timestamp(now()) - as_timestamp(states.automation.plex_recently_added_webhook.attributes.last_triggered) | int > 60 }}'  
  action:
    - service: notify.sms_over_email
      data_template:
        title: 'New Item Added to Plex:'
        message: '{{trigger.json["title"]}}'

That’s pretty much it. With everything running you should be triggering a webhook in Tautulli, based on “recently added” media, then, POST-ing predefined JSON providing the title of the media item to Home Assistant, where a corresponding “automation” is triggered; and finally, the message is forwarded to your mobile via email -> text.

Here is that screenshot again of Home Assistant displaying the recently triggered automation we just set up:

Home Assistant – Logbook, showing the recently triggered automation. Success.

Conclusion

There are other ways to accomplish this, but no other way as awesome as integrating Home Assistant. Tautulli is fun to work with too because it is so well-made and feature-rich. Bringing the two together via webhooks is a great way to automate any Plex event you discover. And sure, this is a lot of work but once it’s set up initially, adding additional automations based on any Plex event via webhooks, is as easy as duplicating/tweaking what you already have.

Leave a Reply

Your email address will not be published. Required fields are marked *