Shelly API – Geräte per URL, RPC und Webhook steuern (Gen1 bis Gen4)

Shellys kannst du nicht nur per App steuern, sondern auch über ganz normale URLs. In diesem Beitrag zeige ich dir Schritt für Schritt, wie du deine Shelly-Geräte über die lokale API im Browser schaltest, wie ein Shelly per Webhook selbst eine URL aufruft und wie du Geräte über die Shelly-Cloud-API von unterwegs steuerst.

Hinweis (Stand Oktober 2026): Shelly hat inzwischen mehrere Gerätegenerationen. Die erste Generation (Gen1) nutzt eine einfache HTTP-API mit Adressen wie /relay/0?turn=on. Alle neueren Geräte (Plus, Pro, Mini, Gen3 und Gen4, kurz Gen2+) arbeiten mit der RPC-API, zum Beispiel /rpc/Switch.Set?id=0&on=true. Ich zeige dir deshalb beide Varianten. Grundlage ist die offizielle API-Dokumentation von Shelly.

Warum sollte man überhaupt die API nutzen

Es gibt viele Gründe, warum du deine Smart Home-Geräte von Shelly über eine API steuern solltest. Der vielleicht wichtigste Grund ist die Sicherheit. Wenn du eine API verwendest, hast du die Kontrolle darüber, wer Zugang zu deinen Geräten hat und was er mit ihnen machen kann. Das ist viel sicherer, als jemandem oder einem Plugin einfach das Passwort für dein Konto zu geben.

Ein weiterer Grund ist die Bequemlichkeit. Es kann viel einfacher sein, eine Automatisierung einzurichten und deine Geräte über eine URL zu steuern als über eine mobile App oder ein Webinterface. Das gilt besonders, wenn du Geräte von verschiedenen Herstellern hast, die vielleicht keine gemeinsame Schnittstelle haben oder nicht alle Funktionen unterstützen.

Ich habe das beispielsweise schon für mein smartes Türöffner-Projekt, den Shelly Button und meinen DIY-Bewässerungscomputer gebraucht. Über diese URL-Aufrufe kannst du deine Shelly-Geräte aus deinem lokalen Netzwerk und über die Shelly-Cloud von überall aus steuern. Im lokalen Netz musst du dafür nur eine simple URL aufrufen, und schon schaltet dein Gerät.

Also lass uns loslegen!

Geräte im lokalen Netzwerk (WLAN) steuern

Der einfachste Weg, deine Shellys zu steuern, ist erst mal das lokale Netzwerk. Hier rufst du tatsächlich nur eine simple URL auf. Bei der Cloud-Steuerung (weiter unten) funktioniert das Ganze etwas anders und komplizierter.

IP Adresse herausfinden

Zuerst musst du herausfinden, welche IP-Adresse dein Shelly-Gerät hat. Schau dazu in der App in den Geräteinformationen nach oder in der Geräteliste deines Routers.

Übrigens: Der Hostname (Gerätename) würde zwar auch funktionieren, aber die IP-Adresse ist zuverlässiger 😉

Gen1 oder Gen2+? So findest du es heraus

Welche Befehle dein Shelly versteht, hängt von seiner Generation ab. Als grobe Faustregel: Gen1 sind die ersten Shellys ohne Zusatz im Namen, etwa Shelly 1, Shelly 1PM, Shelly 2.5, Shelly Plug S, Shelly Dimmer 2, Shelly Button 1 oder Shelly UNI. Steht Plus, Pro, Mini, Gen3 oder Gen4 im Namen, ist es ein Gen2+-Gerät.

Sicher weißt du es, wenn du diese Adresse im Browser aufrufst (mit der IP deines Geräts):

http://192.168.1.12/shelly

Steht in der Antwort ein Feld "gen" mit einer Zahl wie 2, 3 oder 4, nutzt du die RPC-Befehle für Gen2+. Fehlt das Feld, ist es ein Gen1-Gerät. Diese Adresse funktioniert übrigens auch dann ohne Passwort, wenn dein Shelly geschützt ist.

Befehle für Gen2+ (Plus, Pro, Mini, Gen3, Gen4)

Gen2+-Geräte sprechen JSON-RPC. Das klingt komplizierter, als es ist: Für einfache Befehle rufst du /rpc/ plus den Namen der Methode auf und hängst die Parameter an die URL an. Alle Details stehen in der Gen2+-Dokumentation (leider nur auf Englisch). Hier die wichtigsten Befehle, ersetze jeweils IP-DES-SHELLY durch die IP-Adresse deines Geräts:

Gerät	Zweck	Befehl (Gen2+)
Relais / Steckdose (z. B. Shelly 1PM Gen3, Plug S Gen3)	anschalten	http://IP-DES-SHELLY/rpc/Switch.Set?id=0&on=true
Relais / Steckdose	ausschalten	http://IP-DES-SHELLY/rpc/Switch.Set?id=0&on=false
Relais / Steckdose	umschalten	http://IP-DES-SHELLY/rpc/Switch.Toggle?id=0
Relais / Steckdose	60 Sekunden an, danach wieder aus	http://IP-DES-SHELLY/rpc/Switch.Set?id=0&on=true&toggle_after=60
Relais / Steckdose	Status abfragen	http://IP-DES-SHELLY/rpc/Switch.GetStatus?id=0
Zweikanal-Relais (z. B. Shelly 2PM) Kanal 2	anschalten	http://IP-DES-SHELLY/rpc/Switch.Set?id=1&on=true
Rollladen (z. B. Shelly 2PM im Cover-Modus)	öffnen	http://IP-DES-SHELLY/rpc/Cover.Open?id=0
Rollladen	schließen	http://IP-DES-SHELLY/rpc/Cover.Close?id=0
Rollladen	stoppen	http://IP-DES-SHELLY/rpc/Cover.Stop?id=0
Rollladen	auf 50 % fahren	http://IP-DES-SHELLY/rpc/Cover.GoToPosition?id=0&pos=50
Dimmer	anschalten	http://IP-DES-SHELLY/rpc/Light.Set?id=0&on=true
Dimmer	ausschalten	http://IP-DES-SHELLY/rpc/Light.Set?id=0&on=false
Dimmer	an und auf 50 % dimmen	http://IP-DES-SHELLY/rpc/Light.Set?id=0&on=true&brightness=50

Der Parameter id ist die Nummer des Kanals und fängt bei 0 an. Bei Geräten mit mehreren Ausgängen ist der zweite Kanal also id=1. Laut Doku verstehen viele Gen2+-Geräte zusätzlich noch die alten Gen1-Adressen wie /relay/0?turn=on. Der eigentliche Weg sind aber die RPC-Befehle, und nur die findest du durchgehend in der Doku.

Befehle für Gen1

Für die erste Generation gibt es eine eigene Dokumentation des Herstellers (ebenfalls nur auf Englisch). Sie enthält alles darüber, wie du Shellys abfragen, programmieren und verwalten kannst. Hier sind die wichtigsten HTTP-Befehle für Gen1-Geräte, die ich aufgeschrieben habe:

Gerät (Gen1)	Modus	Zweck	Befehl (Gen1)
Shelly 1 / Shelly 1PM / Plug S	–	anschalten	http://IP-DES-SHELLY/relay/0?turn=on
Shelly 1 / Shelly 1PM / Plug S	–	ausschalten	http://IP-DES-SHELLY/relay/0?turn=off
Shelly 2(.5) Kanal 1	relay	anschalten	http://IP-DES-SHELLY/relay/0?turn=on
Shelly 2(.5) Kanal 1	relay	ausschalten	http://IP-DES-SHELLY/relay/0?turn=off
Shelly 2(.5) Kanal 2	relay	anschalten	http://IP-DES-SHELLY/relay/1?turn=on
Shelly 2(.5) Kanal 2	relay	ausschalten	http://IP-DES-SHELLY/relay/1?turn=off
Shelly 2(.5)	roller	öffnen	http://IP-DES-SHELLY/roller/0?go=open
Shelly 2(.5)	roller	schließen	http://IP-DES-SHELLY/roller/0?go=close
Shelly 2(.5)	roller	stoppen	http://IP-DES-SHELLY/roller/0?go=stop
Dimmer/SL	–	anschalten	http://IP-DES-SHELLY/light/0?turn=on
Dimmer/SL	–	ausschalten	http://IP-DES-SHELLY/light/0?turn=off
Dimmer/SL	–	dimmen auf 50%	http://IP-DES-SHELLY/light/0?brightness=50

Wie du siehst, gibt es abhängig von deinem Gerätetyp, der Firmware und den Ausgängen beziehungsweise dem Modus verschiedene Befehle. Such dir aus der passenden Tabelle 👆 einfach dein Gerät und einen Befehl aus.

Testen der Befehls-URL

Mit der Beispiel-IP 192.168.1.12 sieht die fertige URL zum Anschalten eines Gen2+-Geräts so aus:

http://192.168.1.12/rpc/Switch.Set?id=0&on=true

Bei einem Gen1-Gerät wie meinem alten Shelly Plug S sieht dieselbe Aktion so aus:

http://192.168.1.12/relay/0?turn=on

Beide URLs kannst du einfach im Browser aufrufen, und der smarte Stecker schaltet sofort. Im Video siehst du das noch mit dem Gen1-Plug-S:

Sobald die Anfrage verarbeitet wurde, siehst du ein weißes Browserfenster mit der Antwort des Geräts in JSON. Ein Gen1-Shelly meldet dir zum Beispiel, dass "ison" jetzt true ist, also angeschaltet. Ein Gen2+-Gerät antwortet auf Switch.Set mit "was_on", also dem Zustand vor dem Befehl. Den aktuellen Zustand bekommst du dort über Switch.GetStatus im Feld "output".

Shelly UNI Beispiele & Projekte

Was tun bei passwortgeschützten Shellies?

Wenn du die Weboberfläche deines Shellys mit einem Passwort gesichert hast, musst du dich bei jedem Aufruf anmelden. Wie das geht, hängt wieder von der Generation ab.

Gen1 nutzt eine sogenannte „HTTP Basic Authentication“. Klingt erst mal nach Raketenwissenschaft, ist aber kein Problem, denn im Browser lässt sich das relativ einfach übergeben. Schreib einfach die Zugangsdaten vor die IP-Adresse deines Geräts, in der Form http://Benutzername:Kennwort@IP-Adresse. Mit Beispieldaten sieht das so aus:

http://admin:supergeheim@192.168.1.12/relay/0?turn=on

Genau diese Gen1-URLs brauchst du übrigens beim Shelly Button 1 als „URL-Action“, um Geräte per Tastendruck zu steuern. Alternativ kannst du aber auch Szenen verwenden.

Gen2+ arbeitet dagegen mit Digest-Authentifizierung (SHA-256), und der Benutzername ist immer admin. Der Trick mit den Zugangsdaten in der URL ist hier nicht der vorgesehene Weg. Im Browser rufst du die URL einfach ganz normal auf, dann fragt dich der Browser nach Benutzername und Passwort. Dort trägst du admin und dein Geräte-Passwort ein. Im Terminal übernimmt curl die Anmeldung für dich, ersetze dafür DEIN_PASSWORT und die IP:

curl --digest -u admin:DEIN_PASSWORT "http://192.168.1.12/rpc/Switch.Set?id=0&on=true"

Webhooks: Shelly ruft selbst eine URL auf (Actions)

Bisher hast du den Shelly von außen angesprochen. Andersherum geht es auch: Bei einem Ereignis, etwa wenn ein Taster gedrückt wird oder das Relais anschaltet, ruft der Shelly selbst eine URL auf. Das ist ein Webhook. So kann ein Shelly direkt einen anderen Shelly schalten, ganz ohne Cloud oder Smart-Home-Zentrale, oder er gibt Home Assistant Bescheid.

Gen2+: Actions in der Weboberfläche

Ruf die IP-Adresse deines Shellys im Browser auf und öffne den Bereich Actions. Dort legst du eine neue Action an, wählst eine Bedingung (zum Beispiel „Switch on“ oder einen Tastendruck) und trägst die URL ein, die aufgerufen werden soll. Pro Action sind bis zu 5 URLs möglich, die nacheinander ausgeführt werden. Ein Gerät kann laut Doku bis zu 20 Webhooks speichern, batteriebetriebene Geräte bis zu 10.

Soll dein Shelly zum Beispiel einen zweiten Shelly mit der IP 192.168.1.13 umschalten, trägst du diese URL ein:

http://192.168.1.13/rpc/Switch.Toggle?id=0

Praktisch: In der URL kannst du Platzhalter in der Form ${...} verwenden, die der Shelly vor dem Aufruf mit aktuellen Werten füllt. Bei einem Temperatur-Ereignis liefert zum Beispiel ${ev.tC} die Temperatur in °C.

Wenn du lieber per API arbeitest, legst du einen Webhook mit der Methode Webhook.Create an. Dieses Beispiel schaltet beim Einschalten von Kanal 0 (switch.on) den zweiten Shelly an. Ersetze die erste IP durch die des auslösenden Shellys und die URL im Feld urls durch dein Ziel:

curl -X POST -d '{"id":1,"method":"Webhook.Create","params":{"cid":0,"enable":true,"event":"switch.on","name":"Zweiten Shelly an","urls":["http://192.168.1.13/rpc/Switch.Set?id=0&on=true"]}}' http://192.168.1.12/rpc

Welche Ereignisse dein Gerät kennt, verrät dir /rpc/Webhook.ListSupported (ab Firmware 2.0 heißt die Methode Webhook.ListAllSupported). Deine angelegten Webhooks siehst du mit /rpc/Webhook.List.

Gen1: URL-Actions

Gen1-Geräte haben in ihrer Weboberfläche ebenfalls einen Bereich Actions. Dort hinterlegst du für Ereignisse wie „Ausgang an“, „Ausgang aus“ oder einen kurzen Tastendruck eine URL, auch hier bis zu 5 URLs pro Action. Soll der Shelly sich selbst ansprechen, beginnt die URL laut Doku mit http://localhost/. Genau so funktioniert auch die „URL-Action“ beim Shelly Button 1.

Shelly-Webhooks in Home Assistant nutzen

In Home Assistant bindest du Shellys normalerweise über die Shelly-Integration ein (Einstellungen → Geräte & Dienste). Dann brauchst du keine URLs, Home Assistant spricht direkt mit dem Gerät. Ein Webhook ist aber praktisch, wenn ein Shelly ganz gezielt eine Automation starten soll.

Dafür legst du eine Automation mit dem Auslöser „Webhook“ an (wie Automationen grundsätzlich funktionieren, erkläre ich im Home Assistant Automation Tutorial). Home Assistant zeigt dir dort eine Webhook-ID. Die URL für deine Shelly-Action sieht dann so aus:

http://IP-VON-HOME-ASSISTANT:8123/api/webhook/DEINE_WEBHOOK_ID

Wichtig: Ein einfacher URL-Aufruf ist eine GET-Anfrage, und GET ist beim Webhook-Auslöser in Home Assistant standardmäßig nicht aktiv. Öffne deshalb neben der Webhook-ID die Webhook-Einstellungen und erlaube dort zusätzlich GET. Die Option „Nur lokal“ kannst du eingeschaltet lassen, solange Shelly und Home Assistant im selben Netzwerk sind.

Geräte über das Internet (Shelly-Cloud) steuern

Da die Steuerung über die Cloud um einiges komplizierter ist, empfiehlt sich dieser Weg nur für erfahrene oder leidensfähige Smart-Home-Enthusiasten 🙂

Cloud aktivieren

Cloud-Key, Server und Device-ID herausfinden

Von dem Gerät, das du steuern willst, brauchst du außerdem noch die Device-ID. Die findest du in der App beim Gerät unter Einstellungen → Geräteinformationen → Device Id.

Cloud-Befehl herausfinden

Wichtig zu wissen: Für die Cloud gibt es eine eigene Dokumentation. Dort findest du zwei Varianten. Der Abschnitt „Communication (deprecated)“ beschreibt die alte API, bei der die Daten als Formular (application/x-www-form-urlencoded) geschickt werden. Shelly hat angekündigt, dass sie bald entfernt wird. Nimm deshalb die neue Communication v2.0-beta.

Bei v2 schickst du statt URL-Parametern eine kleine JSON-Payload (also den Inhalt der Anfrage) per POST an den Server. Den Cloud-Key hängst du als ?auth_key= an die Adresse. Es gibt eigene Adressen für Relais und Steckdosen (/v2/devices/api/set/switch), Rollläden (/v2/devices/api/set/cover), Licht (/v2/devices/api/set/light) und zum Abfragen des Zustands (/v2/devices/api/get). Laut Doku ist pro Sekunde nur eine Anfrage erlaubt.

Befehl an die Cloud-API senden

Über die Adresszeile im Browser lässt sich die Cloud-API nicht mehr testen, weil sie POST-Anfragen erwartet. Unter macOS und Linux geht das am schnellsten mit curl im Terminal. Ersetze DEIN-SERVER, DEIN_CLOUD_KEY und DEINE_DEVICE_ID durch deine eigenen Werte:

curl -X POST "https://DEIN-SERVER/v2/devices/api/set/switch?auth_key=DEIN_CLOUD_KEY" \
    -H "Content-Type: application/json" \
    -d '{"id":"DEINE_DEVICE_ID","channel":0,"on":true}'

Mit "on":false schaltest du wieder aus. Für einen Rollladen schickst du die Payload an /set/cover und gibst statt on eine position mit, also open, close, stop oder eine Zahl von 0 bis 100. Klappt der Befehl, antwortet die Cloud mit dem HTTP-Status 200.

Wenn du lieber mit einer Oberfläche arbeitest, nimm die Anwendung Postman (Download). Damit kannst du API-Anfragen zusammenklicken und testen, für diesen Zweck reicht die kostenlose Version. Trag dort dieselbe Adresse ein, stell die Methode auf POST und hinterlege die JSON-Payload als Body.

Im Video siehst du, wie das in Postman grundsätzlich aussieht. Achtung: Es zeigt noch die alte, inzwischen als deprecated markierte Cloud-API mit Formular-Daten. Für die neue API nimmst du die Adresse und die JSON-Payload von oben.

Ich hoffe, dieser Beitrag war hilfreich und hat dir gezeigt, wie du deine Shelly-Geräte mit der API steuern kannst. Wenn du Fragen hast oder auf Probleme stößt, schreib mir gerne einen Kommentar.

Vielen Dank fürs Lesen!