Logo Wael's Digital Garden

Simple Oncall Pager with Home Assistant

Problem#

I need a simple pager that allows my clients to page me. The pager should first try to notify me by a Signal message, and if there is no answer, it should call me.

Solution#

High Level Workflow#

  • Frontend: A Cloudflare application deployed at https://page-wael.nasreddine.com, guarded by Google authentication.
  • Ingress: The Cloudflare application leads to a deployment on my Kubernetes cluster via a Cloudflare Tunnel.
  • User Interaction: The deployment serves a simple HTML page that collects the reason for the page.
  • Trigger: Once the user submits the form, the backend sends a POST request to a Home Assistant webhook.
  • Notification: The webhook triggers a Home Assistant automation that sends me a message on Signal containing:
    • The email of the person triggering the page (extracted from the cf-access-authenticated-user-email header).
    • The reason provided.
    • A 4-digit ACK code.

Escalation Policy#

If I reply with the ACK code, the automation stops. As long as I do not ACK, the loop continues:

  1. Wait 2 minutes.
  2. Send a Signal message.
  3. Check the "Call Threshold" (starts at 2 messages).
  4. If the number of messages sent hits the threshold, initiate a Twilio voice call.
  5. Back-off: Every time a call is made, the threshold for the next call increases by 1 (up to a maximum of 5 messages between calls).

Requirements#

  • Home Assistant: Must be installed with an automation webhook created. Note the Webhook ID for the backend configuration.
  • Signal CLI REST API: The automation is currently configured to use Signal for notifications, though this can be adapted.
  • Backend Service: Configured with the Webhook URL and running to receive requests from the Cloudflare Tunnel.
  • Cloudflare Tunnel: Configured locally as cloudflared to forward connections to your private network.
    • Note: The backend currently checks for the cf-access-authenticated-user-email header. This requirement can be removed with a code change if not using Cloudflare Access.
  • Cloudflare Application: To guard the tunnel behind Google authentication.

Home Assistant Automation#

The code is located here 👉🏼 Automation

Backend#

The backend code is available in this GitHub repository. 

Related#