I wanted my Home Assistant to be able to send me alerts when Bad Things are detected like water on my basement floor. I’m an SRE, and have been using PagerDuty for years, so I decided to set up a personal PagerDuty account and connect it to my Home Assistant.

Why PagerDuty and not Twilio SMS? When I was working at Twilio I wrote the blog post on their site about using their API with Home Assistant. The down side of using Twilio to notify is that their API doesn’t have a simple way to mark messages as potential duplicates, so if you have an automation that triggers for some potentially flappy state like motion in the yard you might get 20 messages for the same problem, which is not awesome in the middle of the night.

With PagerDuty, you can specify a dedupe_key and it will automatically ignore new alerts on that key until you resolve the incident, without you having to add any complicated logic to your automations or notify service.

Prerequisites

  1. A working Home Assistant installation. Initial set up of Home Assistant is out of scope for this post - presumably you’re reading this because you already have Home Assistant running and want to enable it to send you notifications
  2. A PagerDuty account. They have a free tier that is probably more than adequate for most people’s needs.

Setup

PagerDuty

Create your PagerDuty account at PagerDuty.com and create a new service. I unimaginatively named mine “Home Assistant”. You’ll also need to configure your notification settings in your profile. If you don’t have their app installed, you can install it now, but PagerDuty can send you SMS messages and you can interact with it that way if you prefer.

In the new service, click the Integrations tab. We’re going to want to use v2 of the Events API to create alerts, so click on the down arrow to the right of Events API V2 to reveal details. We’re going to need both the Integration Key and the Integration URL (Alert Events), so copy them into a scratch file for later.

Schedules

PagerDuty will have created a default schedule for your service, which is great. What’s not great is that it defaults to alerting 24 hours a day - I don’t want to get woken up because of something minor like a network issue, especially on weekends, so I edited my schedule to only be active between 10 am and 10 pm.

Home Assistant

Now we’ll connect PagerDuty to Home Assistant. I didn’t want to install a helper script into my HA system, and conveniently enough you can create alerts using PagerDuty’s API directly, so we’re going to create a rest_command to make the API calls for us.

To keep our configuration.yaml easier to share, we want to use !secret, so first, edit your secrets.yaml file and add a pd_integration_key entry with the integration key you copied from your service’s Integrations tab.

Annoyingly, you can’t directly embed a !secret xyz call inside the rest_command’s payload, so we’re going to have to work around it by creating a sensor (where we can use !secret) and then read that value into the rest_command’s payload template. This is ugly but it works.

Add a pd_routing_key sensor to your configuration.yaml file

sensor:
  - platform: template
    sensors:
      pd_routing_key:
        value_template: !secret pd_integration_key

Now that we’ve defined our sensor, we can refer to its value inside of the payload template in our rest_command, so define a pagerduty_message command by adding the following yaml snippet to your configuration.yaml. I created the payload in this snippet from the examples in PagerDuty’s Incident API documentation.

If the URL you copied for Integration URL (Alert Events) is different than the url key in the snippet, change the url value accordingly.

rest_command:
  pagerduty_message:
    url: https://events.pagerduty.com/v2/enqueue
    method: POST
    payload: >-
      {
        "routing_key":"{{ states('sensor.pd_routing_key') }}",
        "dedup_key":"{{ dedup_key }}",
        "event_action":"trigger",
        "payload":
        {
          "summary":"{{ message }}",
          "source":"{{ source }}",
          "severity":"{{ severity }}",
          "custom_details": {
             "{{custom_title}}": "{{ custom_details }}"
           }
        }
      }

Confirm that you don’t have any typos and your configuration is valid by going to http://yourHA:8123/developer-tools/yaml and clicking CHECK CONFIGURATION. If it reports it valid, you can safely restart HA.

Testing

Click on the services tab on your HA’s developer tools page. Select RESTful Command: pagerduty_message, and then paste the following snippet in.

  • message value is the subject of the alert.
  • dedup_key is used to prevent you from getting spammed with multiple alerts for the same problem. Until you mark an incident as resolved, any new alerts with the same dedup_key value will not generate new alerts. I have a different unique dedup_key for each of my water sensor automations so that if water is detected under one of my sinks, I’ll only get one alert per sink instead of getting a new alert every five minutes for the same problem.
  • severity- must be critical, error, warning, or info
  • custom_title - This will be displayed in the Details section of alerts.
  • custom_details - This will be in the Details section of alerts.
service: rest_command.pagerduty_message
data:
  message: This is the subject line
  dedup_key: a_unique_string
  severity: info
  source: Test Source
  custom_title: Issue
  custom_details: Test alert to PagerDuty

Click the CALL SERVICE button. You should get an alert almost immediately, depending on your personal notification settings. Once that’s working, you can use your new pagerduty_message service in your scripts and automations.