Homebridge SmartThings Webhook Plugin

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.

Features

- 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

Prerequisites

- 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)

---

Quick Start

$3

``
npm install homebridge-smartthings-webhook
`

Or through the Homebridge UI: search for homebridge-smartthings-webhook in the Plugins tab.

---

$3

Run the SmartThings CLI:

Follow the prompts:

| Prompt | Value |
| ------------------ | --------------------------------------------- |
| App Type | OAuth-In App |
| Display Name | Homebridge SmartThings |
| Description | Homebridge integration |
| Icon Image URL | (skip) |
| Target URL | https://httpbin.org/get |
| Scopes | r:devices:, x:devices:, r:locations:* |
| Redirect URI | https://httpbin.org/get |

Save the Client ID and Client Secret - you won't be able to see them again!

---

$3

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

Or without static domain (URL changes each restart)

ngrok http 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.yml

Start 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 SmartApp

Enter 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 errors

Update 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 |

---

Changelog

See CHANGELOG.md for version history.

---

Credits

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.

---

License

MIT