Webhook HTTP binding

Add-on Marketplace Bundles
, ,
1

Webhook Binding

This even lets you describe your own API/WebHooks for OpenHab. This is sometimes needed for external services or hardware that has limited ability to call http webhooks.

Supported Things

Only one thing is supported - webhook. This thing does not have any channels at first but let you add any number of it.

Discovery

Discovery is not supported

Binding Configuration

Main configuration of the created thing lies in its unique id. This is will be part of the url for a webhook endpoint processed by this thing.

Optional config is to fill Response expression / Expression . However for most cases you can leave with

resp.status=200

Channel configuration

Within a channel you configure only an expression property. Configuration is in form of a script written in Apache JEXL language. Return value of this expression will be a value that updates/commands the channel.

As for now in the expression there is only a simple object req which has only two properties:

  1. parameters - under this property all query parameters and form-encoded post parameters are placed. So you can define in your http requests query params and extract it to channels.
  2. body - unders this property the body of the POST requests is stored. body has two properties text and json. With this you can post a json file to you openhab and use an expression to extract an value from the json and place it into channel. See further examples.
  3. method - POST/GET/PUT/DELETE

Context for expressions can be enriched with more than one req object in future.

Example

Following exaple of channel expression will update value of the channel whenever someone make a request to http://[youropenhab]/webhook/[thingid]/[channelid].

if (req.parameters.action[0] == "call") {
  return "CALLING";
};

Suppport this project

You can support this project by sponsoring its maintainers:
Piotr Bojko

Changelog

Please see all release notes here.

Resources

org.openhab.binding.webhook-0.2.0.jar

Release 0.2.0

9 Likes
2

Hey Piotr,
could you have a look? After an update or after a cleancache your binding gets uninstalled by openhab.

3

yeah, could you elaborate more on this? You can log the ticket at github.

4

I don’t think this is unique to the Webhook binding - I’ve seen it happen to other bindings from the marketplace as well.

5

I don’t think, too, that it is unique to webhook binding. But maybe the deletion of bindings appear if the binding does not meet any kind of minimum criteria or some meta data are missing?
It is not a big deal. I just wanted to bring this to the attention of the developer.

6

Just wondering if anyone has any idea how to get this to work with the new Unifi Protect Alarm manager. It has a webhooks option. Im not very familiar with how webhooks work or where to begin.

image
image1386×768 82.1 KB

I created a Channel named Test1

not sure how to edit the above emaple script to get it to do anything .

if (req.parameters.action[0] == "call") {
  return "CALLING";
};

when i go to “http://192.168.2.100:8080/webhook/testProtect/Test1”
the LastCall channel does update. I just am unsure how to script/ what headers i need to add to make this work some how.

This is from UniFi’s Site about webhooks.

Not sure if this helps any

Advanced Settings
By default, the webhook will create an HTTP GET request each time an alarm is triggered.

For advanced cases, use the Advanced Settings:

HTTP GET allows custom headers for security tokens or other additional information.
HTTP POST delivers additional information about the alarm to your service.
Here is an example of the HTTP POST structure:

{
  "alarm": {
    "name": "test post",
    "sources": [],
    "conditions": [
      {
        "condition": {
          "type": "is",
          "source": "motion"
        }
      }
    ],
    "triggers": [
      {
        "key": "motion",
        "device": "74ACB99F4E24"
      }
    ]
  },
  "timestamp": 1722526793954
}

Thanks for any help.

7

Your device supports http/post. You do not need the webhook binding.
Create an http request:
url = ‘http://61:8080/rest/items/testItem’
contentType = “text/plain”
content = “ON”
headers:
‘Accept’: ‘/’
‘Authorization’: ‘Bearer oh.rules.DhBqiiRJiotlpI2…….’

You can create an authorization token in MainUI. Click on your name in the lower left corner.

8

I’ve just configured a Custom Webhook on UniFi to
http://openhabip:8080/webhook/ef07c36f7b/scan
Where “scan” is a trigger channel I’ve added to the thing with expression:

return "ON";

The thing is configured with Response expression:

resp.status=200

Then I’ve created a rule with condition:
When channel webhook:Webhook:ef07c36f7b:scan was triggered

1 Like
9

i am very happy with this binding because it enables me to communicate from my mobotix cameras to openhab (habapp).

i have it working with a thing created in mainui. my code here is:

UID: webhook:Webhook:d74c46e691
label: Webhook thing
thingTypeUID: webhook:Webhook
configuration:
  expression: resp.status=200
channels:
  - id: lastCall
    channelTypeUID: webhook:lastCall-channel
    label: Last request
    description: Timestamp of the last request to the webhook.
    configuration: {}
  - id: mobotixTssPrivat
    channelTypeUID: webhook:trigger-channel
    label: Mobotix TSS-privat
    description: ""
    configuration:
      expression: req.parameters.mobotixTssPrivat[0];
  - id: mobotixTssHoftor
    channelTypeUID: webhook:trigger-channel
    label: Mobotix TSS-Hoftor
    configuration:
      expression: req.parameters.mobotixTssHoftor[0];

i would like to use this data in a things-file but i am lost. i tried several notations like eg:

Thing webhook:Webhook:my_webhook "Webhook call" [
    id="my_webhook",
    expression="req.body"
    // expression="resp.status=200"
] {
    Channels:
    - id: mobotixTssPrivat
        channelTypeUID: webhook:trigger-channel
        label: Mobotix TSS-privat
        description: ""
        configuration:
            expression: req.parameters.mobotixTssPrivat[0];
    - id: mobotixTssHoftor
        channelTypeUID: webhook:trigger-channel
        label: Mobotix TSS-Hoftor
        description: ""
        configuration:
            expression: req.parameters.mobotixTssHoftor[0];
}

but the part with the channels gives me an error. could somebody please point me to the correct notation? thanks in advance.

10

Hello first of all, thanks for this binding.
It brings my MyStorm Buttons to the possibly to use them by Openhab.
I have installed them on OH 5.0.2 and it works perfect.

After I have upgraded from 5.0.2 to 5.0.3 I have have the need, to install the binding manual once again, because it was not there anymore.

The same happens now at the major update from 5.0.3 to 5.1.0-1

What can I do, that also the WebHook binding will be updated and installed automaticly?

Thanks
Jochen

11

I assume you have installed the addon through marketplace. By intention marketplace bindings are removed if their version number does not match to your openhab version.

You could create a rule which reinstalls the binding during start up or copy the binding to your addon folder.

12

Thanks for this information. I was not aware, the bindings from the Marketplace will not be used, when an update happened.