Skip to main content

Webhook

This service allows Shelly devices to send HTTP requests triggered by events. Events usually occur when functional device parts change their state (switch toggling, button pushes, sensor readings, etc.). There is a limit of 20 hook instances per device (10 for battery-operated devices). The same event may trigger any number of webhooks associated with it. A revision number is maintained which is incremented on every update of the schedules. It is returned in the result of RPC calls and is also included in the Status object of the Sys component.

Each webhook is associated with an event type and component instance. The association is determined as follows:

  • The event attribute of a hook is formatted as <component type>.<event type>. It identifies the type of component, and the specific event for this component type.
  • The cid attribute of a hook is the id of the component instance.

<component type> together with <cid> specify the component instance, identified as <component type>:<cid>.

Conditional execution

Some events support attributes - additional pieces of information about the event which occurred.

Hooks support conditions: logical statements which yield a boolean result whether to trigger the webhook or not. The conditions can use information from the system config, status and device info available as config, status and info objects with the same structure as returned by Shelly.GetConfig, Shelly.GetStatus and Shelly.GetDeviceInfo. Additionally, if the event supports attributes, their information is available in an ev or event object. Condition statements must be valid script expressions.

Example: for a webhook associated with a temperature component, Webhook.Create {"cid":0, "enable":true, "event":"temperature.change", "urls":["http://example.com"], "condition":"event.tC > 20"} will only invoke the url if attribute tC of event temperature.change is above 20. In this case the attribute tC of the ev object is used in the condition string.

Repeatability

Hooks support also repeat period: number specifying the minimum interval in seconds for two consecutive invocations of the hook. If events which trigger the hook during this interval occur they will be suppressed. A negative repeat_period is interperted as "never repeat". Such webhooks will only be executed once, as their condition transitions from false to true. The default for repeat_period is 0, which means the webhook will be executed every time the event occurs.

URL token replacement

Hooks events also support url token replacement. Before the url is invoked, it is parsed for notations in format ${token}. token can be a valid javascript expression. ${token} will be replaced with the result of the evaluation of this expression. If evaluation fails the contents of token are copied verbatim. During evaluation the objects config, status, info and ev or event for events with attributes are available as for conditions:

  • status is an object which contains the entire device status as returned by Shelly.GetStatus
  • config is an object which contains the entire device configuration as returned by Shelly.GetConfig
  • info is an object which contains device info as returned by Shelly.GetDeviceInfo

Interpolated token values are urlencoded.

Examples

  • http://example.com/endpoint?tC=${ev.tC} for webhooks associated with temperature.change events will replace ${ev.tC} with the actual temperature measured by the sensor
  • http://example.com/endpoint?hum=${ev.rh}&temp=${status["temperature:0"].tC}&batt=${status["devicepower:0"].battery.V} will include temperature, battery voltage, along with humidity measured by sensor on a PlusHT device, triggered by a humidity.change event.
  • http://example.com/endpoint?uptime=${status.sys.uptime} will include the uptime in seconds as a query string parameter
  • http://example.com/endpoint?mac=${config.sys.device.mac} will include the MAC address of the device as a query string parameter
  • http://example.com/endpoint?switch=${status["switch:0"].output will include output state of Switch component with id 0.
note

For example Webhook.Create {"cid":0, "enable":true, "event":"temperature.change", "urls":["http://example.com/tC=${ev.tC}"]} will replace ${ev.tC} with the actual temperature, for instance http://example.com/tC=20.00.

note

To insert a literal ${ in the url without triggering a replacement, $${ should be used as an escape sequence. That is $${ will get swapped with ${ and no token interpolation will take place. For example, http://example.com/tC=$${ev.tC} will be invoked as http://example.com/tC=${ev.tC}.

note

When upgrading from a firmware version which does not support url token replacement to one which does, existing urls will be migrated: if they contain the ${ literal, it will be swapped with $${.

Webhook.ListSupported

This method lists all supported events that can be used to trigger a webhook.

Request

This method takes no parameters.

Response

Attributes in the result:

PropertyTypeDescription

hook_types

array of type string

Deprecated since 0.11.0 Contains all events that can be used to trigger a webhook.

types

object

Since version 0.11.0 Contains all events that can be used to trigger a webhook, extended with a declaration of supported event attributes. Events are listed as JSON objects with keys in format component type,event type. Supported event attributes, if such exist, are represented in attrs array:

PropertyTypeDescription

name

string

attribute name

type

string

attribute type, one of boolean, number, string

desc

string

attribute description

note

hook_types is deprecated and will be removed from the response of Webhook.ListSupported. Please use types instead.

Webhook.List

This method lists all existing webhooks for this device.

Request

This method takes no parameters.

Response

Attributes in the result:

PropertyTypeDescription

hooks

array of objects

Each entry is a webhook object

PropertyTypeDescription

id

number

Id of the webhook

cid

number

Id of the component

enable

boolean

true to be enabled, false otherwise

event

string

Event which will trigger the execution of the webhook

name

string or null

User-defined name for the webhook instance

ssl_ca

string or null

Type of the TCP socket. Optional

ValueDescription

null or *

Default value, the built-in ca.pem TLS CA is used for HTTPS requests

user_ca.pem

The user-provided TLS CA is used for HTTPS requests, see Shelly.PutUserCA

*

Disabled certificate validation

urls

Containing url addresses that will be called when the webhook event occurs

condition

string or null

Hook trigger condition associated with event.

repeat_period

number

Minimum interval for invocations of the hook.

rev

number

Current revision number of the webhook instances

Webhook.Create

This method creates a webhook instance.

Request

Parameters:

PropertyTypeDescription

event

string

Event which will trigger the execution of the webhook. Valid events are listed by Webhook.ListSupported. Example values: switch.on, input.toggle_off. Required

cid

number

Component instance id Required

enable

boolean

true to be enabled, false otherwise. It is false by default. Optional

name

string or null

User-defined name for the webhook instance. Optional

ssl_ca

string or null

Type of the TCP socket. Optional

ValueDescription

null

Default value, the built-in ca.pem TLS CA is used for HTTPS requests

user_ca.pem

The user-provided TLS CA is used for HTTPS requests, see Shelly.PutUserCA

*

Disabled certificate validation

urls

array of type string

Containing url addresses that will be called when the webhook event occurs. Each url address is limited to 300 characters and the total number of url addresses associate with one webhook is 5. At least one url address is Required

active_between

array of type string

The first element indicates the start of the period during which the webhook will be active, the second indicates the end of that period. Both start and end are strings in the format HH:MM, where HH and MM are hours and minutes with optional leading zeros. To clear active_between its value should be set to empty array or null. When active_between is empty, this attribute is not visible in Webhook.List and the webhook is active all the time. Optional

condition

string or null

Hook trigger condition associated with event. Omitting condition from the request parameters, condition="" and condition=null have the same effect - the condition always evaluates to true. Optional

repeat_period

number

Minimum interval for invocations of the hook. If set to negative the hook will be invoked only once when the condition changes from false to true. If set to 0 the hook will be invoked every time the triggering event occurs. Default is 0.Optional

Response

Attributes in the result:

PropertyTypeDescription

id

number

Id of the created webhook

rev

number

Current revision number of the webhook instances

Webhook.Update

This method updates an existing webhook instance.

Request

Parameters:

PropertyTypeDescription

id

number

Id of the webhook instance to be updated. Required

event

string

Event which will trigger the execution of the webhook. Valid events are listed by Webhook.ListSupported. Example values: switch.on, input.toggle_off. Optional

cid

number

Component instance id. Optional

enable

boolean

true to be enabled, false otherwise. It is true by default. Optional

name

string or null

User-defined name for the webhook instance. Optional

ssl_ca

string or null

Type of the TCP socket. Optional

urls

array of type string

Containing url addresses that will be called when the webhook event occurs. Each url address is limited to 300 characters and the total number of url addresses associate with one webhook is 5. At least one url address must be available. Optional

active_between

array of type string

The first element indicates the start of the period during which the webhook will be active, the second indicates the end of that period. Supported time formats are HH:MM, H:MM, H:M (in the current timezone). To clear active_between its value should be set to empty array or null. When active_between is empty, this attribute is not visible in Webhook.List and the webhook is active all the time. Optional

condition

string or null

Hook trigger condition associated with event. condition="" and condition=null have the same effect - the condition always evaluates to true. Optional

repeat_period

number

Minimum interval for invocations of the hook. If set to negative the hook will be invoked only once when the condition changes from false to true. If set to 0 the hook will be invoked every time the triggering event occurs.Optional

Response

Attributes in the result:

PropertyTypeDescription

rev

number

Current revision number of the webhook instances

Webhook.Delete

This method deletes an existing webhook instance.

Request

Parameters:

PropertyTypeDescription

id

number

Id of the webhook to be deleted. Required

Response

Attributes in the result:

PropertyTypeDescription

rev

number

Current revision number of the webhook instances

Webhook.DeleteAll

This method deletes all existing webhooks.

Request

This method takes no parameters.

Response

Attributes in the result:

PropertyTypeDescription

rev

number

Current revision number of the webhook instances

Examples

Webhook.ListSupported example

http://192.168.33.1/rpc/Webhook.ListSupported

Response

{
"hook_types": [
"input.toggle_on",
"input.toggle_off",
"input.button_push",
"input.button_longpush",
"input.button_doublepush",
"switch.off",
"switch.on",
"temperature.change"
],
"types": {
"input.toggle_on": {},
"input.toggle_off": {},
"input.button_push": {},
"input.button_longpush": {},
"input.button_doublepush": {},
"switch.off": {},
"switch.on": {},
"temperature.change": {
"attrs": [
{
"name": "tC",
"type": "number",
"desc": "New temperature in Celsius"
},
{
"name": "tF",
"type": "number",
"desc": "New temperature in Fahrenheit"
}
]
}
}
}

Webhook.List example

http://192.168.33.1/rpc/Webhook.List

Response

{
"hooks": [
{
"id": 1,
"cid": 0,
"enable": false,
"event": "input.toggle_off",
"name": "When input is OFF",
"urls": [
"http://10.33.55.167/rpc/Switch.Set?id=2&on=false"
],
"condition": null,
"repeat_period": 0
},
{
"id": 2,
"cid": 0,
"enable": true,
"event": "input.toggle_on",
"name": "null",
"urls": [
"http://10.33.55.131/rpc/Switch.Toggle?id=0"
],
"condition": null,
"repeat_period": 0
}
],
"rev": 1
}

Webhook.Create example

http://192.168.33.1/rpc/Webhook.Create?cid=0&enable=true&event="switch.on"&urls=["http://10.33.55.167/rpc/Switch.Set?id=1&on=true&toggle_after=30"]

Response

{
"id": 3,
"rev": 1
}

Webhook.Update example

http://192.168.33.1/rpc/Webhook.Update?id=3&name="WebhookSwitchChain"

Response

{
"rev": 4
}

Webhook.Delete example

http://192.168.33.1/rpc/Webhook.Delete?id=3

Response

{
"rev": 4
}

Webhook.DeleteAll example

http://192.168.33.1/rpc/Webhook.DeleteAll

Response

{
"rev": 4
}