@prs.io/homebridge-smartthings-webhook
v3.0.2TypeScript
Connects SmartThings devices to Homebridge. Automatically discovers devices.
0/weekUpdated 3 days agoApache-2.0Unpacked: 676.8 KB
Published by rgedagit
npm install @prs.io/homebridge-smartthings-webhook
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
- SmartApp Authentication: Simple SmartApp-based auth with automatic token refresh
- Automatic Device Discovery: Finds and adds your SmartThings devices automatically
- New Device Detection: Automatically subscribes to new devices when added in SmartThings
- Crash Loop Protection: Detects repeated failures and prevents Homebridge crashes
- Easy Setup: Step-by-step configuration with UI wizard
Prerequisites
- Homebridge: A working Homebridge installation with UI access
- Public HTTPS URL: A way to expose your Homebridge to the internet (ngrok, Cloudflare Tunnel, or reverse proxy with SSL)
- SmartThings Developer Account: Access to SmartThings Developer Workspace
---
Quick Start
$3
``bash`
npm install @prs.io/homebridge-smartthings-webhook
Or through the Homebridge UI: search for homebridge-smartthings-webhook in the Plugins tab.
---
$3
Your webhook endpoint must be accessible from the internet with a valid HTTPS certificate.
Option A: ngrok (Recommended for beginners)
1. Create a free account at ngrok.com
2. Get a free static domain from ngrok dashboard
3. Install ngrok: brew install ngrok (macOS) or download from ngrok.comngrok config add-authtoken YOUR_TOKEN
4. Configure:
5. Run:
Your URL will be: https://your-name.ngrok-free.app
Option B: Cloudflare Tunnel (Free, more reliable)
1. Install cloudflared: brew install cloudflared
2. Login:
3. Create tunnel:
4. Configure DNS in Cloudflare dashboard
5. Run:
Option C: Reverse Proxy with Let's Encrypt
If you have a domain and static IP, use nginx/Caddy with Let's Encrypt for free SSL certificates.
---
$3
1. Go to SmartThings Developer Workspace
2. Click + New Project → Select Automation for the SmartApp → Name it (e.g., "Homebridge SmartThings")
3. Click REGISTER APP and select Webhook Endpoint
4. Enter your webhook URL:
`
https://your-public-url/smartapp
> ⚠️ Must be HTTPS and include /smartapp at the end!
5. Configure App Details:
- Add a display name and description
- Select OAuth2 scopes: r:devices:, x:devices:, r:locations:*
6. Click SAVE and immediately copy:
- Client ID
- Client Secret (only shown once!)
- App ID (from the app overview page)
---
$3
In your Homebridge config (via UI or config.json):
`json`
{
"platforms": [
{
"platform": "HomeBridgeSmartThings",
"name": "SmartThings",
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"server_url": "https://your-public-url",
"webhook_port": 3000
}
]
}
| Option | Required | Description |
| --------------- | -------- | ------------------------------------------------ |
| client_id | Yes | SmartApp Client ID from Step 3 |client_secret
| | Yes | SmartApp Client Secret from Step 3 |server_url
| | Yes | Your public HTTPS URL (without /smartapp) |webhook_port
| | No | Local webhook server port (default: 3000) |smartapp_id
| | No | SmartApp ID for request validation (recommended) |
---
$3
Start or restart Homebridge. You should see in the logs:
`
[SmartThings] Webhook server listening on port 3000
[SmartThings] SmartApp webhook endpoint: https://your-public-url/smartapp
[SmartThings] SmartApp not installed or credentials not found.
This is expected - the plugin is waiting for you to install the SmartApp.
---
$3
1. Open the SmartThings mobile app
2. Go to Menu (☰) → SmartApps → + (Add)
3. Scroll to My SmartApps or search for your app name
4. Select your location and authorize the app
5. The app will send credentials to your Homebridge
---
$3
After installing the SmartApp, restart Homebridge. You should now see:
`
[SmartThings] SmartApp: Loaded saved credentials for installed app: xxx
[SmartThings] SmartApp credentials found, proceeding with device discovery...
[SmartThings] Discovered 24 devices total from SmartThings
[SmartThings] Direct webhook mode: Registered 24 device IDs with SmartApp handler
Done! Your devices should now appear in HomeKit with real-time updates.
---
How It Works
`
┌─────────────────┐ HTTPS ┌──────────────────┐
│ SmartThings │ ──────────────▶│ Homebridge │
│ Cloud │ Push Events │ (This Plugin) │
└─────────────────┘ └──────────────────┘
│
▼
┌──────────────────┐
│ HomeKit │
└──────────────────┘
1. SmartApp Installation: When you install the SmartApp, SmartThings sends auth tokens to your webhook
2. Device Subscriptions: The plugin creates subscriptions for all your devices
3. Real-Time Events: Device state changes are pushed instantly via webhook
4. Token Refresh: Tokens are automatically refreshed every 12 hours
5. New Device Detection: When you add a new device in SmartThings, it's automatically subscribed
No polling, no relay service, no delays!
---
Configuration Options
| Option | Type | Default | Description |
| ------------------------------ | ------- | ------- | --------------------------------------------- |
| client_id | string | - | SmartApp Client ID |client_secret
| | string | - | SmartApp Client Secret |server_url
| | string | - | Public HTTPS URL for webhooks |webhook_port
| | number | 3000 | Local port for webhook server |smartapp_id
| | string | - | SmartApp ID for request validation |use_direct_webhook
| | boolean | true | Enable direct SmartThings webhooks |IgnoreDevices
| | array | [] | Device names to exclude from HomeKit |ShowOnlyDevices
| | array | [] | Only show these devices (whitelist mode) |IgnoreLocations
| | array | [] | Location names to exclude |PollSensorsSeconds
| | number | 5 | Polling interval for sensors (fallback only) |PollSwitchesAndLightsSeconds
| | number | 10 | Polling interval for switches (fallback only) |enableTelevisionService
| | boolean | true | Enable TV service for Samsung TVs |registerVolumeSlider
| | boolean | false | Add volume control as lightbulb for TVs |
---
Troubleshooting
$3
1. Verify your public URL is accessible:
`bash`
curl -X POST https://your-public-url/smartapp \
-H "Content-Type: application/json" \
-d '{"lifecycle":"PING","pingData":{"challenge":"test"}}'
Should return: {"statusCode":200,"pingData":{"challenge":"test"}}
2. Check Homebridge logs for errors
3. Verify ngrok/tunnel is running and forwarding to port 3000
$3
1. Make sure you installed the SmartApp in the SmartThings mobile app
2. Check that smartthings_smartapp_token.json was created in your Homebridge storage
3. Restart Homebridge after installing the SmartApp
$3
The plugin automatically refreshes tokens every 12 hours. If refresh fails:
1. Check that client_id and client_secret are correct
2. Reinstall the SmartApp in SmartThings mobile app
3. Check Homebridge logs for specific errors
$3
1. In Homebridge UI: Click "Clear All Tokens" button in plugin settings
2. In SmartThings App: Remove the SmartApp:
- Menu (☰) → SmartApps → Find your app → Delete/Remove
3. Restart Homebridge
4. Reinstall SmartApp in SmartThings mobile app
---
File Locations
| File | Purpose |
| --------------------------------- | ------------------------------------------ |
| smartthings_smartapp_token.json | SmartApp credentials (auth/refresh tokens) |crash_loop_log.json
| | Crash loop detection log |
These files are stored in your Homebridge storage directory (usually ~/.homebridge/ or /var/lib/homebridge/`).
---
Changelog
See CHANGELOG.md for version history.
---
Credits
Special thanks to:
- @iklein99 - Original homebridge-smartthings plugin
- @aziz66 - homebridge-smartthings fork with OAuth
This plugin builds upon their excellent work to provide real-time SmartThings integration for Homebridge.
---
License
Apache-2.0