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:

Property	Type	Description
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: Property Type Description name string attribute name type string attribute type, one of boolean, number, string desc string attribute description

Webhook.List

This method lists all existing webhooks for this device.

Request

This method takes no parameters.

Response

Attributes in the result:

Property	Type	Description
hooks	array of objects	Each entry is a webhook object Property Type Description 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 Value Description 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:

Property	Type	Description
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 Value Description 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:

Property	Type	Description
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:

Property	Type	Description
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:

Property	Type	Description
rev	number	Current revision number of the webhook instances

Webhook.Delete

This method deletes an existing webhook instance.

Request

Parameters:

Property	Type	Description
id	number	Id of the webhook to be deleted. Required

Response

Attributes in the result:

Property	Type	Description
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:

Property	Type	Description
rev	number	Current revision number of the webhook instances

Examples

Webhook.ListSupported example

Webhook.ListSupported HTTP GET Request

http://192.168.33.1/rpc/Webhook.ListSupported

Webhook.ListSupported Curl Request

curl -X POST -d '{"id":1,"method":"Webhook.ListSupported"}' http://${SHELLY}/rpc

Webhook.ListSupported Mos Request

mos --port ${PORT} call Webhook.ListSupported

Response

Webhook.ListSupported HTTP GET Response

{
  "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.ListSupported Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "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.ListSupported Mos Response

{
  "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

Webhook.List HTTP GET Request

http://192.168.33.1/rpc/Webhook.List

Webhook.List Curl Request

curl -X POST -d '{"id":1,"method":"Webhook.List"}' http://${SHELLY}/rpc

Webhook.List Mos Request

mos --port ${PORT} call Webhook.List

Response

Webhook.List HTTP GET 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.List Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "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.List Mos 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

Webhook.Create HTTP GET Request

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"]

Webhook.Create Curl Request

curl -X POST -d '{"id":1,"method":"Webhook.Create","params":{"cid":0,"enable":true,"event":"switch.on","urls":["http://10.33.55.167/rpc/Switch.Set?id=1&on=true&toggle_after=30"]}}' http://${SHELLY}/rpc

Webhook.Create Mos Request

mos --port ${PORT} call 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

Webhook.Create HTTP GET Response

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

Webhook.Create Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "id": 3,
    "rev": 1
  }
}

Webhook.Create Mos Response

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

Webhook.Update example

Webhook.Update HTTP GET Request

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

Webhook.Update Curl Request

curl -X POST -d '{"id":1,"method":"Webhook.Update","params":{"id":3,"name":"WebhookSwitchChain"}}' http://${SHELLY}/rpc

Webhook.Update Mos Request

mos --port ${PORT} call Webhook.Update '{"id":3,"name":"WebhookSwitchChain"}'

Response

Webhook.Update HTTP GET Response

{
  "rev": 4
}

Webhook.Update Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "rev": 4
  }
}

Webhook.Update Mos Response

{
  "rev": 4
}

Webhook.Delete example

Webhook.Delete HTTP GET Request

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

Webhook.Delete Curl Request

curl -X POST -d '{"id":1,"method":"Webhook.Delete","params":{"id":3}}' http://${SHELLY}/rpc

Webhook.Delete Mos Request

mos --port ${PORT} call Webhook.Delete '{"id":3}'

Response

Webhook.Delete HTTP GET Response

{
  "rev": 4
}

Webhook.Delete Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "rev": 4
  }
}

Webhook.Delete Mos Response

{
  "rev": 4
}

Webhook.DeleteAll example

Webhook.DeleteAll HTTP GET Request

http://192.168.33.1/rpc/Webhook.DeleteAll

Webhook.DeleteAll Curl Request

curl -X POST -d '{"id":1,"method":"Webhook.DeleteAll"}' http://${SHELLY}/rpc

Webhook.DeleteAll Mos Request

mos --port ${PORT} call Webhook.DeleteAll

Response

Webhook.DeleteAll HTTP GET Response

{
  "rev": 4
}

Webhook.DeleteAll Curl Response

{
  "id": 1,
  "src": "shellypro4pm-f008d1d8b8b8",
  "params": {
    "rev": 4
  }
}

Webhook.DeleteAll Mos Response

{
  "rev": 4
}