Integrating SmartThings with another automation controller via REST API?

Developer Programs Writing SmartApps
1

Hi, I am new to SmartThings but I have made an app that runs on my Homey automation controller that uses the REST API to integrate my ST devices into Homey. Currently the app uses polling to get device status updates, which is obviously not very efficient, so I would like to use webhooks to notify my Homey app when something changes.
As far as I can see the only way to do this is to create a smart app in SmartThings, is that correct?
If so how would I share this with other Homey users so they can also us the app?
Do I need to create an app in the developer portal or does the node.js SDK do that for me?

Homey is able to provide a public call back for the webhook so I would like each device to host that and not one server.

Any help to get me started would be appreciated as I am struggling to get my head around the SmartApp concept.

Many thanks.

2

Welcome @AdyR!

Yes, Subscriptions are a good option to receive the events of the device in your SmartApp and send them elsewhere if needed. You can subscribe by capability or component in the device.

You could host your SmartApp and provide them the URL so they can register it in their Developer Workspace account.

I didn’t quite understand, What is this call back used for?

Here’s a tutorial to get started with the SmartApp NodeJS SDK. I’ll be here to answer any question that comes to your mind.

1 Like
3

Hi, @nayelyz, Thanks for the quick reply.

One thing I can’t quite understand yet is if the SmartApp runs in the SmartThings account or on the external server?

So could the URL be a part of the app that I provide to run on the Homey device?

The aim is for the Homey device to be notified when something happens in their SmartThings account, such as a window or motion sensor being triggered. So I presume each Homey would need to register / receive the webhook.

I have looked at the tutorial but I can’t quite understand what it’s doing with the .page parts. That seems to create a mysterious web page somewhere for the user to select devices.

Just to clarify, Homey is a similar platform to Home Assistant running on a users hardware. So I effectively want Homey user to be able incorporate their ST devices into their Homey such that they can extend their automations, etc, in the same way as Home Assistant.
As I say, using the REST AP I have managed to add lights and sensors and even washing machines and air conditioners in Homey, but the app uses polling to get status changes and I would like to make use of the webhooks.

I appreciate your help and hope I can understand how to do this.

4

It runs in the external server of your preference, in the tutorial, it runs on Glitch.

The URL I meant is the one configured when registering the SmartApp at the “Target URL” field, where all the events/requests are sent.

SmartApp_registration
SmartApp_registration1099Ă—448 25.1 KB

So, you already have an app on the Homey side, and it would receive requests from the SmartThings side, right?
The flow in the SmartApp of SmartThings is:

  1. The user turns something on or, something is detected by the sensors.
  2. An event for the subscription to that component or capability is generated.
  3. The event is received at the subscription’s handler, you get info such as the deviceId, componentId, capabilityId and value. From here, you could send it to Homey, but it depends on how its app works.

This is the SmartApp’s configuration page (belongs to the “Configuration” Lifecycle), where you define the different inputs you need from the user, for example, a list of devices, text (eg. an IP address), or numbers. Here, you can find the list of the settings types.

5

Thanks for the explanations and patience while I get my brain aligned.

When I first started looking at integrating ST about a year ago I setup a SmartApp in my account and when I registered the webhook URL my app in Homey got the verification and responded OK so the URL was stored.
However, when I try to subscribe to anything I just get a 403 error, not authorised.
Yesterday I started a new Homey app using the ST Nodejs library but straight away the app was over 48MB compared to my original app which is 283KB. So that library is very heavy and I can’t make it give me anything that my original app already has.
I then tried the core library which is better at only 3MB but I am still in the same position that any attempt to subscribe just returns the 403 error.
The key that I created has every permission that is available.

When creating the SmartApp it generates a Client ID and Client Secret but I haven’t found anywhere in the SDK to use those so maybe that’s the bit I’m missing. I am using the App ID provided by the SmartApp.

The other issue is that if every homey user has to make a SmartApp in their ST account then it is beyond most users ability. Homey is all about simplicity so a user should only have to install the app, sign in and add devices. At the moment, users having to create a key is beyond some of them.
I was hoping that the Homey app would be able to create everything via code and I can apparently create an app via the core SDK but what is the point if it can’t do anything?

6

Subscriptions are linked to an installedApp. If you’re receiving this error is because the Access Token you’re using is not from a SmartApp or it doesn’t have the permissions needed.
Can you share your configuration with me, please? You can do it through a private repository if you like, my user is nayelyzarazua-bluetrail.

What key do you mean? Up to now, SmartApps cannot be published to appear in the catalog but each user would only have to register it.

7

The Access Token is a PAT and I haven’t worked out how to get the SmartApps token yet.

What do you you want me to share? I can’t see a way to share the Project from my developer workspace.
I have sent you an invite to collaborate on the testing that I am trying. This is just bits that I am trying to find out about.

I was referring to the PAT required to use the API.

Today I was trying to add the SmartApp to my account via the SmartThings app but it says the app is not responding. I was expecting the webhook to be invoked but it was never called. It was called when I set the URL in the project and the response was accepted so I could save the settings.

I really appreciate your time to help me.

8

This is what causes the 403 error, a PAT cannot be used to create a subscription, because it is for non-SmartApp purposes (See the types of Token description on this page).

When you select the SmartApp to install it in the mobile app, the first lifecycle begins. Using the SmartApp SDK, a request for those lifecycles is sent to your SmartApp and its HTTP Callback Handler. It identifies which lifecycle is and the response (according to your configuration) is sent back to SmartThings.

//From the samples:
server.post('/', async (req, res) => {
    app.handleHttpCallback(req, res);
});
9

I had suspected that but I can’t work out how to initiate the OAuth2 authentication.

I have just changed the webhook URL in the developer section and it has pinged my server:

Webhook Post:  {
  lifecycle: 'PING',
  executionId: '7C8EAEA4405F4FAD96C6E6FB788CBA7B-FEYZ',
  locale: 'en',
  version: '0.1.0',
  pingData: { challenge: '3bc71871-db83-4a08-95fe-a6cf4dc87319' },
  settings: {}
}
Post Reply:  { pingData: { challenge: '3bc71871-db83-4a08-95fe-a6cf4dc87319' } }

However, when I try to install the SmartApp in the Mobile app, nothing is hitting my server and i see an error “We’re having trouble connecting. Check…”.
If it were to send the various stages to my webhook URL then I have code in place to respond.
Any idea why it’s not calling my webhook?

10

Hi there!
I checked the information you shared and I suggest you separate your integration into two apps, one for the Homey side to receive the events (it could be using REST) from the SmartThings SmartApp (which uses the NodeJS SDK).
To connect a third-party cloud with the SmartThings environment an Oauth integration is used, but this one needs special permissions.
The SmartApp SDK follows the OAuth process to get the Acess Token that will allow you to interact with the ST elements.