Webhooks and HTTP requests

What this is for

A Shelly device can send an HTTP request when something happens on it — a button is pressed, a relay switches, a sensor crosses a threshold. That request can go to another Shelly, to any device with an HTTP API, or to a service like IFTTT.

This is direct device-to-device control, and its appeal is simple: it runs on the local network, reacts in milliseconds, and needs neither a cloud account nor an internet connection.

Webhooks or LNM?

Since firmware 2.0.0 there are two ways for Shelly devices to talk to each other locally. They are not competitors — they solve different problems.

Use a webhook when the target is not a Shelly, when you need to reach one specific device, or when a device is on older firmware.

Use LNM when several Shelly devices should react together, or when you would otherwise be maintaining a list of reserved IP addresses. On a large installation that difference is the whole argument — see dimming with an input module for a worked example.

Creating an action

Open the device in Shelly Smart Control, at control.shelly.cloud, or directly on its IP address. Go to Settings → Actions and choose Add action. The layout differs slightly between the three, the fields do not.

Name. What it does, not what it is. “Hall switch → kitchen light” beats “Action 1”.

Time. When the action is allowed to fire at all. Leave it open unless there is a reason not to.

Condition. What triggers it — a button press, an output changing, a sensor value.

URL. The request to send. Everything below is about building that.

RPC commands — Gen2 and newer

RPC is the current format, used by Plus, Pro, Gen3 and Gen4 devices. It is structured, it covers every component, and it is what to use unless you are working with a Gen1 device.

The pattern is always the same:

http://DEVICE-IP/rpc/Component.Method?id=0&parameter=value

id is the channel, counting from zero: output 1 is id=0, output 2 is id=1.

Relays

http://192.168.1.50/rpc/Switch.Set?id=0&on=true
http://192.168.1.50/rpc/Switch.Set?id=0&on=false
http://192.168.1.50/rpc/Switch.Toggle?id=0
http://192.168.1.50/rpc/Switch.Set?id=0&on=true&toggle_after=30
http://192.168.1.50/rpc/Switch.GetStatus?id=0

toggle_after is seconds — the output reverts by itself, which is how you build a staircase timer without a schedule.

Lights and dimmers

http://192.168.1.50/rpc/Light.Set?id=0&on=true
http://192.168.1.50/rpc/Light.Toggle?id=0
http://192.168.1.50/rpc/Light.Set?id=0&on=true&brightness=70
http://192.168.1.50/rpc/Light.Set?id=0&brightness=70&transition_duration=300
http://192.168.1.50/rpc/Light.Set?id=0&offset=10
http://192.168.1.50/rpc/Light.DimUp?id=0&fade_rate=3
http://192.168.1.50/rpc/Light.DimDown?id=0&fade_rate=3
http://192.168.1.50/rpc/Light.DimStop?id=0

Three of these are worth knowing well. transition_duration fades over that many seconds — 300 gives a five-minute sunrise. offset shifts brightness by a relative amount, so offset=-10 dims by ten percentage points from wherever it is. And DimUp runs until something stops it, which is why DimStop exists and why hold-to-dim needs a script rather than an action.

Covers

http://192.168.1.50/rpc/Cover.Open?id=0
http://192.168.1.50/rpc/Cover.Close?id=0
http://192.168.1.50/rpc/Cover.Stop?id=0
http://192.168.1.50/rpc/Cover.GoToPosition?id=0&pos=30
http://192.168.1.50/rpc/Cover.Calibrate?id=0

Position needs a calibrated cover — see cover control.

Device level

http://192.168.1.50/rpc/Shelly.GetStatus
http://192.168.1.50/rpc/Shelly.CheckForUpdate
http://192.168.1.50/rpc/Shelly.Update
http://192.168.1.50/rpc/Shelly.Reboot
http://192.168.1.50/rpc/Shelly.FactoryReset

With authentication enabled, the form is http://user:pass@DEVICE-IP/rpc/….

Legacy commands — Gen1

The original format, still supported on Gen1 devices and on many Gen2 devices for backward compatibility. Use it when the device is Gen1; use RPC otherwise.

http://DEVICE-IP/DEVICE-TYPE/CHANNEL?COMMAND&COMMAND

Device type is relay, light, roller, color or white.

http://192.168.1.50/relay/0?turn=on
http://192.168.1.50/relay/0?turn=toggle
http://192.168.1.50/relay/0?turn=on&timer=30

http://192.168.1.50/light/0?turn=on&brightness=70
http://192.168.1.50/light/0?dim=up&step=10
http://192.168.1.50/light/0?dim=stop

http://192.168.1.50/roller/0?go=open
http://192.168.1.50/roller/0?go=to_pos&roller_pos=75

http://192.168.1.50/color/0?turn=on&red=255&green=86&blue=112&white=0
http://192.168.1.50/color/0?turn=on&gain=27

On an RGBW2 in white mode the four channels map to white/0 through white/3.

Gen1 device level

http://192.168.1.50/status
http://192.168.1.50/settings
http://192.168.1.50/ota?update=1
http://192.168.1.50/reboot

Shelly 3EM measurement data

http://192.168.1.50/emeter/0/3em_data
http://192.168.1.50/emeter/0/3em_data.csv

Channels 0, 1 and 2 are the three phases. The CSV form downloads the logged data directly, which is the quickest way to get a month of consumption into a spreadsheet.

Tools

The DDD Wizard generates RPC commands for local control. Pick a device, an action and an IP address, and it builds the URL. Developed by colleagues in Poland and available at dennisdalgaard.github.io/shelly-ddd-wizard-2.0, with the original repository on GitHub.

The official API documentation covers every component and every parameter: shelly-api-docs.shelly.cloud. This page covers what is used most; that one covers everything.

Tips & best practices

• Test the URL in a browser first. Paste it into the address bar and see what the device returns. An action that does nothing and a URL that is wrong look identical from the app.
• Reserve the target’s IP address. It is the single most common reason a working webhook stops working months later.
• Name actions after their effect. In two years the URL will mean nothing and the name will be all you have.
• Prefer RPC on anything Gen2 or newer. Legacy commands still work, but they cannot reach components that did not exist in Gen1.
• Consider LNM before building ten actions. Ten devices reacting to one button is ten webhooks to maintain, or one LNM group.

Video tutorial

Direct device-to-device control set up from scratch, with the action fields explained.

Loads YouTube when you press play. Watch on YouTube

By ShellyGuide on YouTube

Related guides