Automating UniFi Protect Alarms and Webhooks with Home Assistant

Introduction

This post continues my UniFi G4 Doorbell Pro and Home Assistant series.
In Part 2, we’ll dive into UniFi Protect alarms and how to use webhooks to trigger automations in Home Assistant.

In Part 1, I shared my experience living with the G4 Doorbell Pro after 18 months of use and how it integrates with Home Assistant for basic monitoring and LCD message control.

This follow-up covers the UniFi Protect alarms and how to use webhooks to connect real-time events like doorbell rings, motion detection, and package deliveries to your Home Assistant setup.

One area where UniFi Protect Alarm webhooks can be very handy is with Line Crossing events. The line crossing event isn’t exposed in the Home Assistant UniFi Protect integration, but I ran into a problem with my LLM Vision setup. Sometimes the UniFi Protect person-detected sensor would trigger the automation too early, capturing an image of a person still far from the doorbell. With the line crossing event, I can draw a line on the camera view and send a webhook to Home Assistant when that line is crossed.

Resources in This Post

ChrisHansenTech is a participant in the Amazon Services LLC Associates Program, an affiliate advertising program designed to provide a means for sites to earn advertising fees by advertising and linking to Amazon.com. As an Amazon Associate I earn from qualifying purchases.

Hardware

• UniFi G4 Doorbell Pro PoE Kit
• UniFi Dream Machine Special Edition

Software and Services

• Webhook.site - Service to send webhooks to for testing and to see the payload.

Understanding UniFi Protect Alarms

UniFi Protect includes an Alarm Manager that can generate events for motion, doorbell presses, and system alerts. You can configure these alarms to send HTTP webhooks to any endpoint—making them ideal for triggering Home Assistant automations.

UniFi Protect Alarm Manager screen

These examples are based on UniFi Protect 6.1.78 and UniFi OS 4.3.6 running on a UniFi Dream Machine SE. Your interface may look slightly different depending on firmware version.

Creating a webhook automation in Home Assistant

1. Open Home Assistant, and go to Settings → Automations & scenes.
2. Select Create automation → Create new automation.
3. Click Add trigger.
4. Search for Webhook and select Webhook trigger.
5. Home Assistant will automatically generate a Webhook ID.
6. Click the gear icon and make sure POST and Only accessible from the local network are selected.

Home Assistant Webhook

For now, complete the automation by sending a simple mobile notification:

1. Click Add action.
2. Search for your mobile app notification service.
3. In Message, enter Someone is at the door.
4. In Title, enter Doorbell.
5. Click Save.
6. Name your automation and click Save again.

Here’s the YAML for the automation you just created:

alias: Doorbell Webhook
description: "Doorbell event triggered from a webhook"
triggers:
  - trigger: webhook
    allowed_methods:
      - POST
      - PUT
    local_only: true
    webhook_id: "-iH-UwnSFn8FClOXmJLShCuwi"
conditions: []
actions:
  - action: notify.mobile_app_[YOUR_PHONE]
    metadata: {}
    data:
      message: Someone is at the door
      title: Doorbell
mode: single

Creating a UniFi Protect Alarm to send a webhook

With the webhook automation ready in Home Assistant, we can now create an alarm in UniFi Protect to send that webhook.

1. Open UniFi Protect.
2. Click Alarm Manager → Create Alarm.
3. Type Home Assistant Doorbell Press for the alarm name.
4. Click Activity.
5. Check Ring.
6. In Scope, select your doorbell device.
7. In Action, click Webhook.
8. Change the default Slack Post to Custom Webhook.
9. In Delivery URL, enter your Home Assistant webhook address:
   • http://[your_home_assistant]:8123/api/webhook/[your_hook_id]
10. Under Advanced Settings, select POST.
11. Click Test Alarm → Test Alarm, then confirm you receive the notification.
12. Click Create to save the new alarm.

Home Assistant Companion App Notification

UniFi Protect Create Alarm

The Use Thumbnails option sends the image as a Base64-encoded string. There isn’t an easy way to use that data in Home Assistant.

Using the webhook payload

In our basic automation example, we only used the receipt of an HTTP POST request as the trigger. This means that anything with the webhook URL could send a POST request and trigger the automation. We also didn’t make use of any data contained in the webhook payload.

There aren’t many good resources showing what data UniFi Protect includes in its webhook payload. This is where a service like Webhook.site comes in handy. You can point your webhook URL to the address generated by Webhook.site and view the full JSON payload that UniFi Protect sends.

Here is the JSON for our doorbell alarm, I have put placeholders in parts of the data, with placeholders to show what each value represents.

{
    "alarm": {
        "name": "Home Assistant Doorbell Press",
        "sources": [
            {
                "device": "[DEVICE_MAC_ADDRESS]",
                "type": "include"
            }
        ],
        "conditions": [
            {
                "condition": {
                    "type": "is",
                    "source": "ring"
                }
            }
        ],
        "triggers": [
            {
                "key": "ring",
                "device": "[DEVICE_MAC_ADDRESS]",
                "eventId": "[EVENT_ID]",
                "timestamp": 1760282368873
            }
        ],
        "eventPath": "/protect/events/event/[EVENT_ID]",
        "eventLocalLink": "https://192.168.1.X/protect/events/event/[EVENT_ID]"
    },
    "timestamp": 1760282369282
}

With the JSON payload in hand, we can make our automation more specific so it only triggers when the doorbell event occurs. We’ll update our notification automation so it only fires when it’s the doorbell event—and even include the eventLocalLink as part of an actionable notification.

1. Edit the Doorbell Webhook automation.
2. Click Add condition
3. Search for template and click Template.
4. Type in {{ trigger.json.alarm.sources[0].device == "[DEVICE_MAC_ADDRESS]" }}
5. Click the notification in the Then do section.
6. Add the follwing YAML to the data property

  actions:
    - action: URI
      title: Open event
      uri: "{{ trigger.json.alarm.eventLocalLink }}"

The full YAML for our notification is now.

alias: Doorbell Webhook
description: ""
triggers:
  - trigger: webhook
    allowed_methods:
      - POST
      - PUT
    local_only: true
    webhook_id: "-iH-UwnSFn8FClOXmJLShCuwi"
conditions:
  - condition: template
    value_template: "{{ trigger.json.alarm.sources[0].device == \"[DEVICE_MAC_ADDRESS]\" }}"
actions:
  - action: notify.mobile_app_[YOUR_PHONE]
    metadata: {}
    data:
      message: Someone is at the door
      title: Doorbell
      data:
        actions:
          - action: URI
            title: Open event
            uri: "{{ trigger.json.alarm.eventLocalLink }}"
mode: single

Now if we trigger the Home Assistant webhook from another device in UniFi Protect or from a CURL command such as curl -X POST -H "Content-type: application/json" -d '{ "test": "testing" }' http://192.168.1.x:8123/api/webhook/-iH-UwnSFn8FClOXmJLShCuwi the automation will not fire because the condition is not true.

Home Assistant Automation Traces

Additionally, when the automation does fire we can open the UniFi Protect link in a web browser on our phone with the actionable notification.

iPhone Actionable Notification

Testing and debugging

If a webhook is not firing:

• Double-check that your Home Assistant URL is externally reachable if Protect is on a separate VLAN.
• Use the History in Alarm Manager to confirm events are firing.
• Watch the Home Assistant logs (home-assistant.log) for incoming webhook requests.

Once you confirm it’s working, you can start chaining automations, such as:

• Flashing porch lights when the doorbell rings.
• Showing a “Someone’s Here” message on an indoor display.
• Sending a snapshot from the doorbell camera to your phone.

Sending a webhook from Home Assistant to UniFi Protect

You can also send a webhook from Home Assistant to UniFi Protect to trigger an action inside Protect. This lets you use Home Assistant automations to control features like triggering the chime to play a sound and other actions.

For example, you might trigger the doorbell chime when a motion sensor detects someone approaching at night.

We can do this using a rest_command in Home Assistant. First, create an alarm in UniFi Protect.

UniFi Protect Webhook Alarm Trigger

Add the following rest_command to your configuration.yaml file in Home Assistant.

rest_command:
  unifi_protect_trigger:
    url: "https://[UNIFI_IP]/proxy/protect/integration/v1/alarm-manager/webhook/[PROTECT_WEBHOOK_ID]"
    method: post
    headers:
      X-API-KEY: [UNIFI_API_KEY]
    verify_ssl: false

You can then call the command in an automation like this:

alias: Trigger UniFi Protect Chime
triggers:
  - trigger: state
    entity_id: 
      - binary_sensor.front_door_motion
    to: "on"
actions:
  - action: rest_command.unifi_protect_trigger

This step closes the loop, letting UniFi Protect and Home Assistant talk to each other in both directions.

Wrapping up

Webhooks and alarms open up a new level of control between UniFi Protect and Home Assistant.

In the next part, I’ll cover how to use NFC and fingerprint access with the UniFi G4 Doorbell Pro for secure and personalized smart home entry.

Related posts in this series

• Part 1: Living with the UniFi G4 Doorbell Pro
• Part 2: Automating UniFi Protect Alarms and Webhooks (you’re here)
• Part 3: NFC and Fingerprint Access with Home Assistant (coming soon)
• Part 4: Custom Animations and Sounds with Home Assistant (coming soon)
• Part 5: Advanced Project (in development)