How to Effectively Integrate UniFi Protect Webhooks with OpenHAB

General
1

Hello everyone,

I recently went through the process of integrating UniFi Protect webhooks with OpenHAB, and I wanted to share my experience and solution with the community. This guide is aimed at those who want to automate their smart home systems using UniFi Protect’s webhook events, such as fingerprint scans or NFC tag readings.

The Challenge

Initially, I tried using OpenHAB’s native REST API to command items directly from UniFi Protect webhooks. However, I encountered several issues:

  • Method Limitations: UniFi Protect only supports GET and POST methods, while OpenHAB expects PUT for state updates.
  • Content-Type Mismatch: UniFi Protect’s POST requests use application/json, which doesn’t align with OpenHAB’s expected text/plain.
  • Read-Only GET Requests: GET requests can’t update items, making them unsuitable for automation.

The Solution

After some research and troubleshooting, I discovered that the Webhook Binding in OpenHAB is the perfect solution. Here’s how I set it up:

Step 1: Install the Webhook Binding

  1. Open the OpenHAB UI.
  2. Navigate to Settings > Bindings.
  3. Search for and install the Webhook Binding.

Step 2: Create the Webhook Thing

Add the following configuration to your .things file:
plaintext
Thing webhook:webhook:unifi_webhook “UniFi Webhook” [ id=“unifi_webhook”, expression=“req.body” ]

This creates a webhook endpoint at http://[your-openhab-ip]:8080/webhook/unifi_webhook.

Step 3: Set Up the LastCall Channel

The Webhook Thing automatically provides a built-in lastCall channel, which updates whenever the webhook is received. Link this channel to a DateTime Item:
plaintext
DateTime UniFi_Protect_Webhook_Last_request { channel=“webhook:webhook:unifi_webhook:lastCall” }

Step 4: Create a Rule Based on LastCall Changes

You can trigger automation when the webhook fires by watching for changes to the lastCall item. Here’s an example rule:
plaintext
rule “UniFi Webhook Trigger via LastCall Item”
when
Item UniFi_Protect_Webhook_Last_request changed
then
logInfo(“Fingerprint”, “Scan matched – unlocking front door…”)
// Send the UNLOCK command to your lock
sFrontDoorLockSwitch.sendCommand(OFF)
end

Step 5: Configure the Webhook in UniFi Protect

  1. Log into your UniFi Protect account.
  2. Navigate to the webhook setup.
  3. Set the method to POST and enter the endpoint URL created earlier.
  4. Save the configuration.

Important Notes

  • No Custom Headers: UniFi Protect doesn’t allow custom headers, so ensure your OpenHAB setup doesn’t require them.
  • Reliable Automation: Using the lastCall channel is the most reliable method to detect webhook triggers without additional proxies or software.

Conclusion

By leveraging the Webhook Binding, I was able to seamlessly integrate UniFi Protect’s webhook events into my OpenHAB setup. This method is clean, reliable, and doesn’t require any extra software or complex configurations. I hope this guide helps others achieve similar automation in their smart homes!

Best regards,
[Your Name]