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. The same event may trigger any number of webhooks associated with it. Here are listed all methods supported by Webhook:

Webhook.ListSupported#

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

Request#

This method takes no parameters.

http://192.168.33.1/rpc/Webhook.ListSupported

Response#

Attributes in the result:

  • hook_types: array of type string, contains all events that can be used to trigger a webhook
{
"hook_types": [
"input.toggle_on",
"input.toggle_off",
"input.button_push",
"input.button_longpush",
"input.button_doublepush",
"switch.off",
"switch.on"
]
}

Webhook.List#

This method lists all existing webhooks for this device.

Request#

This method takes no parameters.

http://192.168.33.1/rpc/Webhook.List

Response#

Attributes in the result:

  • hooks: array of JSON objects, each entry is a webhook object
    • 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
      • 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: array of type string, containing url addresses that will be called when the webhook event occurs
A device with two existing webhooks. The first turns off the switch with id=2 of the device with IP 10.33.55.167 when the input with id=0 of the SHELLY host is turned off. The second toggles the switch with id=0 of the device with IP 10.33.55.131 when the input with id=0 of the SHELLY host is turned on.
{
"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"
]
},
{
"id": 2,
"cid": 0,
"enable": true,
"event": "input.toggle_on",
"name": "null",
"urls": [
"http://10.33.55.131/rpc/Switch.Toggle?id=0"
]
}
]
}

Webhook.Create#

This method creates a webhook instance.

Request#

Parameters:

  • cid: number, id of the component. Required
  • enable: boolean, true to be enabled, false otherwise. It is false by default. Optional
  • event: string, event which will trigger the execution of the webhook. Valid events are available at Webhook.ListSupported. Example values: switch.on, input.toggle_off. Required
  • name: string or null, user-defined name for the webhook instance. Optional
  • ssl_ca: string or null, type of the TCP socket. Optional
    • 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: 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 containing 2 elements 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. The time format is HH:MM. 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
Create a webhook that turns on the switch with id=1 of the device with IP 10.33.55.167 30 seconds after the switch with id=0 of the SHELLY host is turned on.
curl -X POST -d '{"id":1, "src":"user_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

Response#

Atributes in the result:

  • id: number, id of the created webhook

Webhook.Update#

This method updates an existing webhook instance.

Request#

Parameters:

  • id: number, id of the webhook instance to be updated. Required
  • enable: boolean, true to be enabled, false otherwise. It is true by default. Optional
  • event: string, event which will trigger the execution of the webhook. Valid events are available at Webhook.ListSupported. Example values: switch.on, input.toggle_off. Optional
  • name: string or null, user-defined name for the webhook instance. Optional
  • ssl_ca: string or null, type of the TCP socket. Optional
    • 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: 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 containing 2 elements 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. The time format is HH:MM. 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
http://192.168.33.1/rpc/Webhook.Update?id=3&name=WebhookSwitchChain

Response#

Attributes in the result:

  • id: number, id of the updated webhook
The webhook with id=3 is updated.
{
"id": 3
}

Webhook.Delete#

This method deletes an existing webhook instance.

Request#

Parameters:

  • id: number, id of the webhook to be deleted. Required
http://192.168.33.1/rpc/Webhook.Delete

Response#

Attributes in the result:

  • id: number, id of the deleted webhook
Webhook with id=3 is deleted.
{
"id": 3
}

Webhook.DeleteAll#

This method deletes all existing webhooks.

Request#

This method takes no parameters.

http://192.168.33.1/rpc/Webhook.DeleteAll

Response#

Attributes in the result:

  • ok: boolean, true if the method has been successful and all existing webhooks are deleted, false otherwise
{
"ok": true
}