Webhooks with OpenHAB Using the Webhook Binding
Hi everyone,
After a lot of testing and troubleshooting, I wanted to share a full, working guide on how to integrate UniFi Protect webhook events into OpenHAB — specifically for the new fingerprint scanner and NFC tag reader features available on the UniFi G4 Doorbell Pro.
My goal was to automatically trigger OpenHAB automations when a fingerprint or NFC badge scan was recognized at the doorbell — for example, to unlock a smart lock or disarm an alarm — without needing any external proxy servers, header rewrites, or extra software.
This guide explains why direct REST API methods fail, and shows the correct setup using the Webhook Binding.
Why It Matters
At first, I tried using OpenHAB’s native REST API to command items directly from UniFi Protect webhooks.
However:
- UniFi Protect webhooks only allow GET or POST methods.
- PUT, which OpenHAB would accept for state updates, is not supported by UniFi Protect.
- POSTs from UniFi Protect always have Content-Type:
application/json, and you cannot customize headers. - OpenHAB REST API expects Content-Type:
text/plainwhen POSTing commands. - GET requests are allowed by UniFi, but GET cannot update items (GET is read-only).
Result:
Direct REST API calls from UniFi Protect cannot reliably command OpenHAB items because of method and Content-Type mismatches.
The Solution: Use the Webhook Binding
The Webhook Binding in OpenHAB:
- Accepts POSTs regardless of Content-Type.
- Does not need authentication headers.
- Lets you react flexibly inside OpenHAB.
However, some quirks exist (described below).
Step-by-Step Setup
1. Install the Webhook Binding
- Open OpenHAB UI → Settings → Bindings → Install Webhook Binding.
2. Create the Webhook Thing (Text File)
Create a Thing in your .things file:
Thing webhook:webhook:unifi_webhook "UniFi Webhook" [
id="unifi_webhook",
expression="req.body"
]
Important:
You must specify anexpression, even if you don’t actually use it.
(req.bodyorresp.status=200both work.)
This creates a webhook endpoint at:
http://[your-openhab-ip]:8080/webhook/unifi_webhook
3. Use the Built-In LastCall Channel (No Manual Channel Creation)
The Webhook Thing automatically provides a built-in lastCall channel.
This is a DateTime value that updates whenever the webhook is received.
You do not need to manually create any additional channels.
Simply link the lastCall channel to a DateTime Item:
DateTime UniFi_Protect_Webhook_Last_request { channel="webhook:webhook:unifi_webhook:lastCall" }
4. Set Up a Rule Based on LastCall Changes
You can trigger automation when the webhook fires by watching for changes to the lastCall item.
Example rule:
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
5. Set Up Webhook in UniFi Protect
Inside UniFi Protect:
- Method:
POST - URL:
http://[your-openhab-ip]:8080/webhook/unifi_webhook
- Headers: (None — UniFi does not allow custom headers)
- Body: automatically generated by protect and ignored in this guide.
Now, whenever the event happens (fingerprint, motion, etc.), the webhook will fire and OpenHAB will update the lastCall item.
Important Technical Summary
| HTTP Method | Supported by UniFi Protect? | Can Update OpenHAB? | Problem |
|---|---|---|---|
| GET | Yes | No (read-only) | Cannot command items |
| POST | Yes | Normally yes, but uses wrong Content-Type (application/json) |
|
| PUT | No | Yes (but UniFi cannot send PUT) |
Final Notes
- Webhook Things can be defined in text files.
- No manual channels are needed — just use the built-in
lastCall. - UniFi Protect webhooks only support POST and GET (no PUT).
- POSTs always use
application/json, and headers cannot be customized. - Using the
lastCallchannel is the easiest and most reliable method to detect webhook triggers.
Thus, the Webhook Binding is the cleanest and most reliable method to integrate UniFi Protect with OpenHAB.
