Home Assistant

Home Assistant notifications

Vantyr can forward alert-rule matches to Home Assistant as a custom event. Home Assistant then decides how to react — mobile push, TTS, lights, scenes — while Vantyr only fires a structured event. This keeps the notification logic in HA where it belongs.

Under the hood, when an alert rule matches, the Vantyr server does a server-side POST to Home Assistant's REST API:

POST {HOME_ASSISTANT_URL}/api/events/{event_type}
Authorization: Bearer {HOME_ASSISTANT_ACCESS_TOKEN}
Content-Type: application/json

The JSON body becomes trigger.event.data inside your HA automation.

---

1. Create a long-lived access token in Home Assistant

1. In Home Assistant, click your user/profile (bottom-left).
2. Open the Security tab → scroll to Long-Lived Access Tokens.
3. Click Create Token, name it (e.g. vantyr), and copy it now — HA shows it only once.

A bearer token is preferred over a webhook trigger: it's revocable in HA, keeps the secret out of the URL, and delivers the full JSON payload to your automation.

---

2. Configure the Vantyr server

Set these environment variables on the Vantyr server (see Configuration), then restart the server/container.

Variable	Required	Default	Notes
HOME_ASSISTANT_URL	yes	—	Base URL, e.g. https://homeassistant.local:8123. Must start with http:// or https://. Trailing slash is trimmed.
HOME_ASSISTANT_ACCESS_TOKEN	yes	—	The long-lived token from step 1. Supports a _FILE variant for Docker secrets.
HOME_ASSISTANT_EVENT_TYPE	no	vantyr_alert	The HA event type to fire. Must match [a-z0-9_]+ (lowercase letters, digits, underscores; must start with a letter; ≤100 chars). An invalid value disables the notifier.
HOME_ASSISTANT_SKIP_TLS_VERIFY	no	false	Skips TLS certificate verification — see the caveat below.
PUBLIC_BASE_URL	recommended	—	Public dashboard URL, e.g. https://vantyr.example.com. Enables deep-link fields in the payload.

Both HOME_ASSISTANT_URL and HOME_ASSISTANT_ACCESS_TOKEN are required — if either is missing, the Home Assistant notifier is simply not registered (Vantyr boots normally without it).

What gets sent

The event payload (trigger.event.data) contains:

Field	Description
event_id	DB id of the stored alert event.
rule_id / rule_name	The alert rule that matched.
channel	Telemetry channel that triggered (e.g. keystrokes, url, window).
agent_id / agent_name	The agent that produced the match.
snippet	The matched text snippet.
ts	Match timestamp (epoch).
dashboard_url	Deep link to the agent (only when PUBLIC_BASE_URL is set).
dashboard_activity_url	Deep link to the agent Activity timeline at the event time (only when PUBLIC_BASE_URL is set).

Delivery is fire-and-forget: the server dispatches the HA call on a background task off the alert hot path, and a failed call is logged (warn) without blocking alerting. A per-(rule, agent) cooldown prevents notification spam.

---

3. React to the event in Home Assistant

You can either import the ready-made blueprint or write a small automation by hand.

Option A — Import the Vantyr blueprint (recommended)

1. In Home Assistant go to Settings → Automations & Scenes → Blueprints.

2. Click Import Blueprint and paste this raw URL:

   https://raw.githubusercontent.com/gladsonsam/Vantyr/main/server/src/notify/vantyr_notification.yaml
   

3. Create a new automation from the imported blueprint and select your mobile_app (Companion) device. Optionally set a title prefix, notification icon (MDI name), and color.

The blueprint triggers on vantyr_alert, derives the notify.mobile_app_* service from the chosen device, builds the message from rule_name / agent_name / channel / snippet, and makes the push tappable — opening dashboard_activity_url (falling back to dashboard_url) so you land on the agent timeline at the event time. (Deep links require PUBLIC_BASE_URL on the server.)

If you set a custom HOME_ASSISTANT_EVENT_TYPE, update the blueprint/automation trigger to match.

Option B — Hand-written automation

alias: Vantyr alert → mobile push
trigger:
  - platform: event
    event_type: vantyr_alert        # match HOME_ASSISTANT_EVENT_TYPE
action:
  - service: notify.mobile_app_your_phone
    data:
      title: "Vantyr: {{ trigger.event.data.rule_name }}"
      message: >-
        {{ trigger.event.data.agent_name }} ({{ trigger.event.data.channel }}):
        {{ trigger.event.data.snippet }}
      data:
        # Tap to open the dashboard (requires PUBLIC_BASE_URL on the server).
        # iOS uses `url`; Android uses `clickAction`.
        url: "{{ trigger.event.data.dashboard_activity_url | default(trigger.event.data.dashboard_url | default('')) }}"
        clickAction: "{{ trigger.event.data.dashboard_activity_url | default(trigger.event.data.dashboard_url | default('')) }}"

You're not limited to push — swap the action for tts.speak, light.turn_on, a scene, or anything else HA supports.

---

4. TLS verification caveat

If your Home Assistant uses a self-signed certificate, you may be tempted to set HOME_ASSISTANT_SKIP_TLS_VERIFY=true. This makes Vantyr accept any certificate for HA calls (the server logs a warning at startup), which exposes the bearer token to a man-in-the-middle. Avoid it. Prefer one of:

• a proper certificate (e.g. Let's Encrypt, or an internal CA HA trusts), or
• reaching HA over http:// on a trusted LAN segment, or
• a reverse proxy in front of HA that presents a valid certificate.

Only use HOME_ASSISTANT_SKIP_TLS_VERIFY=true as a temporary measure on a fully trusted network.

---

Troubleshooting

• No events in HA: confirm both HOME_ASSISTANT_URL and HOME_ASSISTANT_ACCESS_TOKEN are set and the server was restarted. Watch HA's Developer Tools → Events, listen for your event type, and trigger a matching alert rule.
• Notifier silently disabled: check the Vantyr server logs for a warning about an invalid HOME_ASSISTANT_EVENT_TYPE (must be [a-z0-9_]+) or a URL missing the http(s):// scheme.
• No deep link in the push: set PUBLIC_BASE_URL on the server.

---

See also: Usage · Configuration · Features · Security · Deployment.