HTML5 Push Notifications

The HTML5 Push Notifications integration lets WoowTech deliver push messages straight into a supported web browser, so you can be alerted on a laptop or phone without installing a native app.

Where it works

Web push is available on a fairly wide range of browsers and platforms:

• Desktop (Windows, macOS, Linux): Chrome, Chromium, Firefox, Edge, Brave, Opera, and Vivaldi.
• Android: the same browser line-up as desktop.
• iOS / iPadOS 16.4 and newer: only when WoowTech is installed as a progressive web app (PWA).

Before you begin

A few conditions have to be met for browser push to function:

• WoowTech must be reachable from outside your home network over HTTPS — or you must be able to complete the domain-verification step instead.
• A valid SSL/TLS certificate has to be in place. Terminating TLS at a reverse proxy counts.
• The browser has to be granted permission to show notifications.
• Brave users: switch on "Use Google services for push messaging" in Brave's privacy settings, otherwise registration won't complete.
• If your reverse proxy enforces HTTP Basic Auth, turn that authentication off temporarily while you register the device — the registration callback needs to get through.

Setting it up

1. Open the configuration shortcut, or go to Settings > Devices & services manually.
2. Choose Add Integration and pick HTML5 Push Notifications.
3. Enter an email address, and optionally paste in a VAPID private key. Leave the key blank and one is generated for you.
4. Open your user profile and switch on the Receive notifications toggle.
5. When the browser asks, approve the notification permission prompt.
6. Give this device a recognizable name.

What the integration provides

Notify target

A notify entity is created so you can push messages with the html5.send_message action.

Events

Three events fire as a notification moves through its lifecycle:

The event payload carries fields such as the notification's tag, the action that was pressed, the target, a type, and any custom data you attached when sending.

Actions

• Send message (html5.send_message) — push a tailored notification that can include an image, action buttons, and arbitrary metadata.
• Dismiss message (html5.dismiss_message) — programmatically clear a notification that's already on screen.

Sending a rich notification

This automation pushes a notification with a title, body, an embedded image, and two action buttons when a door is left open. The tag lets you replace or dismiss this exact notification later.

automation:
  - alias: "Alert when garage door stays open"
    triggers:
      - trigger: state
        entity_id: cover.garage_door
        to: "open"
        for:
          minutes: 10
    actions:
      - action: notify.html5_devices
        data:
          title: "Garage still open"
          message: "The garage door has been open for 10 minutes."
          target:
            - laptop_browser
          data:
            tag: "garage-open"
            image: "https://example.local/garage.jpg"
            actions:
              - action: "close_garage"
                title: "Close it"
              - action: "ignore"
                title: "Leave open"

Reacting to a button press

When the recipient taps a button, an html5_notification.clicked event arrives carrying the chosen action. Match on it to close the garage automatically.

automation:
  - alias: "Close garage from notification"
    triggers:
      - trigger: event
        event_type: html5_notification.clicked
        event_data:
          action: "close_garage"
    actions:
      - action: cover.close_cover
        target:
          entity_id: cover.garage_door

Clearing a notification

script:
  clear_garage_alert:
    sequence:
      - action: html5.dismiss_message
        data:
          target:
            - laptop_browser
          data:
            tag: "garage-open"

Reverse proxy behind NGINX

When a proxy in front of WoowTech requires authentication, the registration callback that the browser sends back can get blocked. Add a dedicated location block that lets the callback through while still refusing requests that carry no authorization header:

location /api/notify.html5/callback {
    if ($http_authorization = "") {
        return 403;
    }
    allow all;
    proxy_pass http://127.0.0.1:8123;
    proxy_set_header Host $host;
    proxy_redirect http:// https://;
}

Caveats and troubleshooting

Exactly which features survive depends on the browser and operating system in play, so behavior won't be identical everywhere. Both delivery of the notification and receipt of the lifecycle events depend on a working internet connection. If something misbehaves, turn on debug logging before opening a report so you have detail to share.

Removing it

Go to Settings > Devices & services, open the HTML5 Push Notifications integration, and pick Delete from its overflow menu.