Connects SmartThings devices to Homebridge. Automatically discovers devices.
npm install @rgedagit/homebridge-smartthings-webhook
A SmartThings plugin for Homebridge with direct webhook support for real-time device updates. No relay service required - events are pushed directly from SmartThings to your Homebridge instance.
- Direct Webhook Support: Real-time device updates without a relay service
- OAuth Authentication: Secure authentication with automatic token refresh
- Automatic Device Discovery: Finds and adds your SmartThings devices automatically
- No Legacy App Required: Works with the new SmartThings app and API
- Easy Setup: Step-by-step configuration with UI wizard
- Homebridge: A working Homebridge installation with UI access
- SmartThings CLI: Download and install the official SmartThings CLI tool
- Public URL (for webhooks): A way to expose your Homebridge to the internet (ngrok, Cloudflare Tunnel, or static IP with port forwarding)
---
```
npm install homebridge-smartthings-webhook
Or through the Homebridge UI: search for homebridge-smartthings-webhook in the Plugins tab.
---
Run the SmartThings CLI:
Follow the prompts:
| Prompt | Value |
| ------------------ | --------------------------------------------- |
| App Type | OAuth-In App |Homebridge SmartThings
| Display Name | |Homebridge integration
| Description | |https://httpbin.org/get
| Icon Image URL | (skip) |
| Target URL | |r:devices:
| Scopes | , x:devices:, r:locations:* |https://httpbin.org/get
| Redirect URI | |
Save the Client ID and Client Secret - you won't be able to see them again!
---
ngrok creates a secure tunnel to expose your local Homebridge to the internet.
#### 3.1 Create Account & Get Auth Token
1. Create a free ngrok account at https://ngrok.com/signup
2. Get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken
3. Get a free static domain (recommended):
- Go to https://dashboard.ngrok.com/domains
- Click "New Domain" to claim your free static domain
- You'll get a domain like your-name.ngrok-free.app
#### 3.2 Install ngrok
macOS (Homebrew):
``
brew install ngrok
Linux (Debian/Ubuntu):
``
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
| sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \
&& echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
| sudo tee /etc/apt/sources.list.d/ngrok.list \
&& sudo apt update && sudo apt install ngrok
Or download from https://ngrok.com/download
#### 3.3 Configure ngrok
``Add your auth token
ngrok config add-authtoken YOUR_AUTH_TOKEN
#### 3.4 Test ngrok manually
`With static domain (recommended)
ngrok http --url=your-name.ngrok-free.app 3000
#### 3.5 Set Up ngrok as a systemd Service (Linux)
To run ngrok automatically on boot before Homebridge starts:
Step 1: Create the ngrok config file
`
mkdir -p ~/.config/ngrok
nano ~/.config/ngrok/ngrok.yml
`Add the following content:
`
version: "2"
authtoken: YOUR_AUTH_TOKEN
tunnels:
homebridge:
addr: 3000
proto: http
url: your-name.ngrok-free.app
`Step 2: Install ngrok as a service (Easy Method)
ngrok has a built-in command to install itself as a systemd service:
`
Install ngrok as a system service
sudo ngrok service install --config ~/.config/ngrok/ngrok.ymlStart the service
sudo ngrok service start
`That's it! ngrok will now start automatically on boot.
Check status:
`
sudo ngrok service status
or
sudo systemctl status ngrok
`View logs:
`
journalctl -u ngrok -f
`Uninstall the service:
`
sudo ngrok service uninstall
`---
Alternative: Manual systemd Setup (if you need custom configuration)
If you need ngrok to start before Homebridge specifically:
Create the systemd service file:
`
sudo nano /etc/systemd/system/ngrok.service
`Add the following content (replace
YOUR_USER with your username):`
[Unit]
Description=ngrok tunnel for Homebridge
After=network-online.target
Wants=network-online.target
Before=homebridge.service[Service]
Type=simple
User=YOUR_USER
ExecStart=/usr/local/bin/ngrok start homebridge --config /home/YOUR_USER/.config/ngrok/ngrok.yml
Restart=on-failure
RestartSec=5
Give ngrok time to establish tunnel before homebridge starts
ExecStartPost=/bin/sleep 3[Install]
WantedBy=multi-user.target
RequiredBy=homebridge.service
`> Important: The
Before=homebridge.service and RequiredBy=homebridge.service ensure ngrok starts before Homebridge and that Homebridge waits for ngrok.Step 3: Find ngrok path (update ExecStart if different):
`
which ngrok
`Step 4: Update Homebridge service to depend on ngrok
`
sudo nano /etc/systemd/system/homebridge.service
`Add or modify the
[Unit] section to include:`
[Unit]
Description=Homebridge
After=network-online.target ngrok.service
Wants=network-online.target
Requires=ngrok.service
`Step 5: Reload and enable services
`
sudo systemctl daemon-reload
sudo systemctl enable ngrok.service
sudo systemctl start ngrok.service
`Step 6: Verify ngrok is running
`
sudo systemctl status ngrok.service
`Step 7: Restart Homebridge (it will now wait for ngrok)
`
sudo systemctl restart homebridge.service
`View ngrok logs:
`
journalctl -u ngrok -f
`Check boot order:
`
systemctl list-dependencies homebridge.service
`#### 3.6 Set Up ngrok with launchd (macOS)
To run ngrok automatically on boot on macOS:
Create the ngrok config file at
~/.config/ngrok/ngrok.yml:Create the launchd plist file:
Add the following content:
Find ngrok path and update the plist if needed:
Load the service:
Check status:
> Tip: The free ngrok plan includes 1 free static domain. Using a static domain means you don't need to update your SmartApp URL each time you restart ngrok.
---
$3
This app receives real-time events from SmartThings.
Make sure ngrok is running and note your public URL (e.g.,
https://your-name.ngrok-free.app)Start the Homebridge plugin first (so it can respond to the confirmation request):
- Configure the plugin with your ngrok URL (see Step 5)
- Start Homebridge
- Verify ngrok is forwarding to port 3000
Create the SmartApp:
Select App Type: Choose
Webhook SmartAppEnter App Details:
Enter Target URL - Use your ngrok URL with
/smartapp:> Important: Make sure to include
/smartapp at the end!Select Scopes - Use arrow keys and space to select:
Press Enter when done.
Domain Confirmation - The CLI will send a CONFIRMATION request to your webhook:
Check your Homebridge logs - you should see:
If successful, the CLI will show:
Save the App ID - You'll need this if you need to update the app later:
$3
"Confirmation failed" or timeout:
- Make sure Homebridge is running with the plugin configured
- Verify ngrok is running and forwarding to port 3000
- Check that
server_url in your config matches your ngrok URL
- Check Homebridge logs for errorsUpdate Target URL later:
If you need to change the URL (e.g., new ngrok domain):
`
smartthings apps:update YOUR_APP_ID
`---
$3
In your Homebridge
config.json or through the UI:`
{
"platforms": [
{
"platform": "HomeBridgeSmartThings",
"name": "SmartThings",
"client_id": "YOUR_OAUTH_CLIENT_ID",
"client_secret": "YOUR_OAUTH_CLIENT_SECRET",
"server_url": "https://YOUR-PUBLIC-URL",
"webhook_port": 3000,
"use_direct_webhook": true
}
]
}
`| Option | Description |
| -------------------- | ------------------------------------------- |
|
client_id | OAuth Client ID from Step 2 |
| client_secret | OAuth Client Secret from Step 2 |
| server_url | Your public URL (without /smartapp) |
| webhook_port | Port for the webhook server (default: 3000) |
| use_direct_webhook | Set to true to enable direct webhooks |---
$3
1. Open the SmartThings mobile app
2. Go to Menu → SmartApps → + (Add)
3. Scroll down and tap "My SmartApps" or find "Homebridge Webhook"
4. Select your location and authorize the app
---
$3
Restart Homebridge to complete the setup. Check the logs for:
`
SmartApp: Loaded saved credentials for installed app: xxx
Direct webhook mode: Registered 24 device IDs with SmartApp handler
Direct webhook mode: Device subscriptions created
`---
How It Works
1. SmartApp Installation: When you install the SmartApp in SmartThings, it sends credentials to your webhook
2. Device Subscriptions: The plugin creates subscriptions for each of your devices
3. Real-Time Events: When a device state changes, SmartThings pushes the event directly to your Homebridge
4. HomeKit Update: The plugin processes the event and updates HomeKit immediately
No polling, no relay service, no delays!
---
Troubleshooting
$3
Check that your public URL is accessible:
Verify subscriptions were created:
Check Homebridge logs for errors
$3
1. Make sure you completed domain confirmation during
smartthings apps:create
2. Try: smartthings apps:register YOUR_APP_ID$3
The plugin automatically refreshes OAuth tokens. If issues persist:
1. Re-run the OAuth wizard in plugin settings
2. Restart Homebridge
$3
If you need to completely reset the plugin authentication:
1. In Homebridge UI: Click "Clear All Tokens" button in the plugin settings
2. In SmartThings App: Remove the SmartApp installation:
- Open SmartThings mobile app
- Go to Menu (☰) → SmartApps
- Find "Homebridge SmartThings"
- Tap and select "Delete" or "Remove"
3. Restart Homebridge
4. Re-authorize: Go through the OAuth wizard again
> Important: If you only clear tokens in Homebridge but don't remove the SmartApp from SmartThings, you may have orphaned subscriptions that won't receive events properly.
---
Configuration Options
| Option | Type | Default | Description |
| ------------------------------ | ------- | ------- | --------------------------------------- |
|
use_direct_webhook | boolean | false | Enable direct SmartThings webhooks |
| server_url | string | \- | Public URL for webhooks |
| webhook_port | number | 3000 | Local port for webhook server |
| PollSensorsSeconds | number | 5 | Polling interval for sensors (fallback) |
| PollSwitchesAndLightsSeconds | number | 10` | Polling interval for switches |---
See CHANGELOG.md for version history.
---
Special thanks to:
- @iklein99 - Original homebridge-smartthings plugin
- @aziz66 - homebridge-smartthings fork with direct webhook support
This plugin builds upon their excellent work to provide real-time SmartThings integration for Homebridge.
---
MIT