405
edits
Changes
New page: Webhooks
<languages/>
<translate>
'''Webhooks''' connect the Larnitech system with any internet service that can send or receive HTTP requests (for example [[IFTTT (IF This, Then That)|IFTTT]]). They are set up in LT Setup on the '''Webhooks''' tab, which has two parts:
* '''Events''': the Larnitech server sends an HTTP request to an external URL when something happens in the system.
* '''Actions''': an external service sends an HTTP request to the Larnitech server, and the server changes the state of an item.
== Events ==
An event has the following fields:
{|class="wikitable"
!Field!!Description
|-
|Name||Name of the event. It is used in the script that sends the event.
|-
|URL||Address that the server calls.
|-
|Method||<code>GET</code> (default) or <code>POST</code>.
|-
|Feedback||Optional. Item address and a regular expression: the value found in the answer is written to that item.
|}
The event is sent from a script. In LT Setup open '''Scripts → Scripts from logic → Add Blockly script''', add the device event on the '''Triggers''' tab, put the '''Make webhook''' block from the '''Automation''' tab into it and choose the event name.
== Actions ==
An action has a name, an item and the state to set (on, off, reverse, level, mode, target temperature and so on, depending on the item type).
To run an action, call the URL:
* in the local network: <code><nowiki>http://CONTROLLER_IP/webhook/?key=API_KEY&name=ACTION_NAME</nowiki></code>
* over the internet: <code><nowiki>https://service.larnitech.com/webhook/?key=API_KEY&sn=SERIAL&name=ACTION_NAME</nowiki></code>
where:
* <code>API_KEY</code>: API key of the server (the <code>TCP-API</code> key, see [[API2]]);
* <code>SERIAL</code>: serial number of the server;
* <code>ACTION_NAME</code>: name of the action from the '''Name''' field.
The server answers with JSON. An error answer has <code>"result":"ERROR"</code> and a message, for example <code>Error Key</code> (wrong key) or <code>Action not found</code>.
== Example ==
The settings are stored in <code>/home/settings/webhooks.json</code>. Example with one event with feedback and two actions:
<syntaxhighlight lang="json" line>
{
"events": [
{
"name": "997:1_button_pressed",
"url": "https://maker.ifttt.com/trigger/997:1_button_pressed/with/key/YOUR_IFTTT_KEY",
"method": "POST"
},
{
"name": "447:145_sensor_state",
"url": "https://example.com/weather.json",
"feedback": { "addr": "447:145", "regexp": "/\"temp\":\"(-?[0-9]+)\",/" }
}
],
"actions": [
{
"name": "401:1_lamp_on",
"status": [ { "request": "status-set", "addr": "401:1", "status": { "state": "on" } } ]
},
{
"name": "401:1_lamp_reverse",
"status": [ { "request": "status-set", "addr": "401:1", "status": { "state": "reverse" } } ]
}
]
}
</syntaxhighlight>
See also: [[IFTTT (IF This, Then That)]], [[API2]].
</translate>
<translate>
'''Webhooks''' connect the Larnitech system with any internet service that can send or receive HTTP requests (for example [[IFTTT (IF This, Then That)|IFTTT]]). They are set up in LT Setup on the '''Webhooks''' tab, which has two parts:
* '''Events''': the Larnitech server sends an HTTP request to an external URL when something happens in the system.
* '''Actions''': an external service sends an HTTP request to the Larnitech server, and the server changes the state of an item.
== Events ==
An event has the following fields:
{|class="wikitable"
!Field!!Description
|-
|Name||Name of the event. It is used in the script that sends the event.
|-
|URL||Address that the server calls.
|-
|Method||<code>GET</code> (default) or <code>POST</code>.
|-
|Feedback||Optional. Item address and a regular expression: the value found in the answer is written to that item.
|}
The event is sent from a script. In LT Setup open '''Scripts → Scripts from logic → Add Blockly script''', add the device event on the '''Triggers''' tab, put the '''Make webhook''' block from the '''Automation''' tab into it and choose the event name.
== Actions ==
An action has a name, an item and the state to set (on, off, reverse, level, mode, target temperature and so on, depending on the item type).
To run an action, call the URL:
* in the local network: <code><nowiki>http://CONTROLLER_IP/webhook/?key=API_KEY&name=ACTION_NAME</nowiki></code>
* over the internet: <code><nowiki>https://service.larnitech.com/webhook/?key=API_KEY&sn=SERIAL&name=ACTION_NAME</nowiki></code>
where:
* <code>API_KEY</code>: API key of the server (the <code>TCP-API</code> key, see [[API2]]);
* <code>SERIAL</code>: serial number of the server;
* <code>ACTION_NAME</code>: name of the action from the '''Name''' field.
The server answers with JSON. An error answer has <code>"result":"ERROR"</code> and a message, for example <code>Error Key</code> (wrong key) or <code>Action not found</code>.
== Example ==
The settings are stored in <code>/home/settings/webhooks.json</code>. Example with one event with feedback and two actions:
<syntaxhighlight lang="json" line>
{
"events": [
{
"name": "997:1_button_pressed",
"url": "https://maker.ifttt.com/trigger/997:1_button_pressed/with/key/YOUR_IFTTT_KEY",
"method": "POST"
},
{
"name": "447:145_sensor_state",
"url": "https://example.com/weather.json",
"feedback": { "addr": "447:145", "regexp": "/\"temp\":\"(-?[0-9]+)\",/" }
}
],
"actions": [
{
"name": "401:1_lamp_on",
"status": [ { "request": "status-set", "addr": "401:1", "status": { "state": "on" } } ]
},
{
"name": "401:1_lamp_reverse",
"status": [ { "request": "status-set", "addr": "401:1", "status": { "state": "reverse" } } ]
}
]
}
</syntaxhighlight>
See also: [[IFTTT (IF This, Then That)]], [[API2]].
</translate>