Use UniFi G4 Doorbell Fingerprint to Unlock Home Assistant Lock

Register your fingerprint

Registering fingerprints is done via the UniFi Protect mobile app.

1. Open the app and select your G4 Doorbell Pro from the Devices list
2. Navigate to Settings > Fingerprints
3. Tap Add New Fingerprint
4. Follow the on-screen instructions to register your fingerprints

You can also register NFC cards if you prefer to use them.

HA 2024.12 or Later (Native Support)

If you are running Home Assistant version 2024.11 or earlier, you can either update to at least 2014.12 or skip down to the instructions on using webhooks to trigger the unlock automation.

Create Home Assistant Automation

The automation will be triggered by a state change of the G4 Doorbell with an event_type of either identified or not_identified. A condition template will check between these two event types and call the unlock action when an identified fingerprint is scanned.

Create a new automation

1. In Home Assistant, go to Settings > Automations & Scenes
2. Click Create Automation and choose Create New Automation

Add Automation Event Trigger

1. Under When, search for and select Manual Event
2. Enter state_changed in the Event type text box
3. In the Event data text box, enter the following where event.front_door_fingerprint is the entity_id for your G4 Doorbell Pro

Add Trigger Condition

1. Under And If, select Add Condition
2. Search for and select Template
3. Copy and paste the following into the text box

{{
   not trigger.event.data.old_state.attributes.get('restored', false) and
   not trigger.event.data.old_state.state == 'unavailable' and
   trigger.event.data.new_state is not none and
   trigger.event.data.new_state.attributes.event_type == 'identified' and
   (trigger.event.data.new_state.attributes.ulp_id|default('')) != ''
}}

This template is taken directly from the official Home Assistant documentation and checks for new scans of identified fingerprints. An identified fingerprint refers to any fingerprint that has been registered in the Protect app.

Add Automation Action

Now that we have a way of triggering this automation we can setup the actions the webhook will take. In this case we want to unlock a lock but this could be setup to do anything that HA can do like sending a notification, turning on/off lights, opening a garage door, etc.

1. Under Then Do, click Add Action.
2. In the Search Action box, type “unlock” and select Lock: Unlock.
3. Click Choose Device, search for, and select the lock to unlock
   • If required, enter a code to unlock the lock
4. Click Save, name your automation, and click Save again.

Your automation should now be visible from the Automations screen.

HA 2024.11 or earlier (Webhooks)

If you’re using version 2024.12 or later and completed the steps above, you can skip these instructions and proceed to the Test section.

Create Home Assistant Automation

The automation will be triggered by a webhook from UniFi Protect, calling the unlock action on your desired lock.

Create a new automation

1. In Home Assistant, go to Settings > Automations & Scenes
2. Click Create Automation and choose Create New Automation

Add Automation Webhook Trigger

1. Under When, select Other Triggers
2. Scroll to bottom and select Webhook
3. Click the settings cog to the right of the Webhook ID box
4. Ensure POST and Only accessible from the local network are selected

The webhook trigger should now be setup. A random Webhook ID will be generated. You can leave it as is or customize it.

Add Automation Action

Now that we have a way of triggering this automation we can setup the actions the webhook will take. In this case we want to unlock a lock but this could be setup to do anything that HA can do like sending a notification, turning on/off lights, opening a garage door, etc.

1. Under Then Do, click Add Action.
2. In the Search Action box, type “unlock” and select Lock: Unlock.
3. Click Choose Device, search for, and select the lock to unlock
   • If required, enter a code to unlock the lock
4. Click Save, name your automation, and click Save again.

Your automation should now be visible from the Automations screen.

You can now trigger this automation by issuing a POST request to the following URL. Replace <haURL> with your Home Assistant URL or IP, and <webhookID> with your generated Webhook ID.

http://<haURL>/api/webhook/<webHookID>

An example full URL would be

http://192.168.40.100:8123/api/webhook/-LtRD7o1EUXbAhfzLUT1varMj

Call Webhook from UniFi Protect

Next, configure UniFi Protect to call the webhook when a recognized fingerprint is successfully scanned.

1. Open your UniFi Protect instance in a browser or the mobile app.
2. Click the Alarm Manager icon in the bottom-left corner.

3. Click Create Alarm
4. Under the Trigger section, select Activity
5. Choose Fingerprint Scan and specify the fingerprints to use, or select All Registered Fingerprints
6. Click Save

7. Under the Scope section, select your G4 Doorbell Pro where fingerprints were registered

8. Under the Action section, choose Webhook
9. Select Custom Webhook from the dropdown and enter your Home Assistant webhook URL in the Delivery URL box
10. Select Advanced Settings and set the method to POST

12. Name your alarm, e.g., Call HA Webhook on Fingerprint Scan
13. Click Save

Comments