Send device health info through webhook endpoint

sandra-nestor · December 15, 2022, 9:09pm

Hi there!
I faced the problem. I can select the device capability healthCheck only using European accounts. When I use my UA account, I cannot select this capability in order to use it in SmartApp.

Also, when I send GET request to the /devices/<deviceId>/health endpoint, I receive information about online/offline status of the device, which is a bit weird:)

The questions are:

Why can I not subscribe to healthCheck capability?
Can I send this information to my webhook endpoint in the SmartApp?

What I’m trying to do is to add a new feature to our app to tell devices are offline. I need to subscribe to HealthCheck capability and use CheckInterval property(I guess…) to ping devices with some frequency. And I want to have these events sent via Webhook endpoint in our SmartApp.

Can someone help me? Tagging @nayelyz
Thanks

orangebucket · December 15, 2022, 9:34pm

Rather than subscribing to the Health Check capability, subscribe to DEVICE_HEALTH.

nayelyz · December 15, 2022, 10:20pm

Hi, @sandra-nestor!

The correct place to get the health status is this endpoint /devices/<deviceId>/health. The healthCheck capability is no longer used to provide this status. It was only used by DTHs which will be deprecated soon.
For Hub-Connected devices that work with Edge drivers, the health check (ping) is handled internally. So, if you subscribe to the event mentioned by @orangebucket, you should get an event in your Webhook indicating if the device changed its state to offline/online.

sandra-nestor · December 16, 2022, 11:47am

Thank you, @nayelyz @orangebucket! I’ll try that)

sandra-nestor · December 20, 2022, 12:31pm

Hi @nayelyz @orangebucket, I have successfully subscribed to DEVICE_HEALTH, but I can’t understand how it works((

As you can see, I have a 200 response code, so my device_health subscription has definitely been created.

But when my device goes offline, I don’t receive any info about the changed device status on my webhook endpoint(but I can see it in the SmartThings app).
I haven’t found any docs concerning DEVICE_HEALTH. So should I receive info that the device goes offline immediately? Or are there some settings on how often online/offline status is updated?

And also, I suspect that online/offline status will be provided in the ‘EVENT’ lifecycle, am I right?

sandra-nestor · December 20, 2022, 1:28pm

It seems that I found a bug here. When we take out the battery from our motion sensor while it has active motion event, the offline status isn’t updated. It remains with ‘motion detected’ status, currently for more than an hour:((

These two motion sensors are without batteries, so they are offline. But as you can see, the first one displays incorrect status.

nayelyz · December 20, 2022, 2:07pm

You should receive it once the device is marked offline, did you define the correct event handler? It is different from a capability subscription, its name is subscribedDeviceHealthEventHandler.

Correct, it will tell you the type of event and provide the deviceId involved.

Is it the same in the API’s health endpoint or only in the app?

sandra-nestor · December 21, 2022, 2:19pm

Thanks for the reply, @nayelyz.

Yes, this was the same in the API’s health endpoint. But today it seems to work fine. The status is updated within 15-20 mins.

We are using only your API, I used this endpoint. Payload:

{
      sourceType: 'DEVICE_HEALTH',
      deviceHealth: {
        subscriptionName: 'device_health_subscription',
        deviceIds: [device_ids]
      }
    }

All event handling we do on our side. And also, we log all events that are coming to our webhook endpoint (before processing it). So I’m 100% sure I don’t miss anything.

nayelyz · December 21, 2022, 2:31pm

Ah, ok. Then, it might have been a glitch, you said it is working fine now, right? If the problem persists it would be good to know if the device is handled by a DTH or Edge driver.

sandra-nestor · December 22, 2022, 10:32am

No, I haven’t received any events from my device_health_subscription yet…
I meant that the offline status is behaving ok in the SmartThings app now. Maybe it was a glitch.

Our devices are handled by Edge drivers. When I make a request to list all subscriptions, I see DEVICE_HEALTH in the list:

{
    "items": [
        {
            "id": "dfca-4237",
            "installedAppId": "eca3d3d5",
            "sourceType": "DEVICE",
            "device": {
                "deviceId": "7843396a",
                "componentId": "main",
                "capability": "*",
                "attribute": "*",
                "value": "*",
                "stateChangeOnly": true,
                "subscriptionName": "button_0_subscription",
                "modes": []
            }
        },
        {
            "id": "d9a75c27",
            "installedAppId": "eca3d3d5-26cd",
            "sourceType": "DEVICE",
            "device": {
                "deviceId": "23c90510",
                "componentId": "main",
                "capability": "*",
                "attribute": "*",
                "value": "*",
                "stateChangeOnly": true,
                "subscriptionName": "contactSensor_0_subscription",
                "modes": []
            }
        },
        {
            "id": "c14198ff",
            "installedAppId": "eca3d3d5",
            "sourceType": "DEVICE",
            "device": {
                "deviceId": "2c5b376",
                "componentId": "main",
                "capability": "*",
                "attribute": "*",
                "value": "*",
                "stateChangeOnly": true,
                "subscriptionName": "motionSensor_0_subscription",
                "modes": []
            }
        },
        {
            "id": "c02a276d",
            "installedAppId": "eca3d3d5",
            "sourceType": "DEVICE",
            "device": {
                "deviceId": "1bc5fcd0",
                "componentId": "main",
                "capability": "*",
                "attribute": "*",
                "value": "*",
                "stateChangeOnly": true,
                "subscriptionName": "motionSensor_1_subscription",
                "modes": []
            }
        },
        {
            "id": "618584d4",
            "installedAppId": "eca3d3d5",
            "sourceType": "DEVICE_HEALTH",
            "deviceHealth": {
                "deviceIds": [
                    "1bc5fcd0",
                    "23c90510",
                    "2c5b376a",
                    "7843396a"
                ],
                "subscriptionName": "device_health_subscription",
                "locationId": "*"
            }
        }
    ],
    "_links": {}
}

So I cannot get it. I have a subscription to devices health. Why events are not coming?((

orangebucket · December 22, 2022, 12:19pm

Have you tried the subscription using the locationId rather than the individual deviceIds?

sandra-nestor · December 22, 2022, 1:54pm

Hmm, I tried, its not working. I receive 403 response code

The payload is:

{
      sourceType: 'DEVICE_HEALTH',
      deviceHealth: {
        subscriptionName: 'device_health_subscription',
        locationId: location_id
      }
    }

I take the locationId from INSTALL lifecycle data.

nayelyz · December 22, 2022, 9:57pm

Hi, @sandra-nestor.
Indeed using the locationId is better as @orangebucket said. There’s a limit of 20 DeviceIDs to use in the array of the subscription.
I created the subscription using the SDK and this is what I found getting it’s details from the API:

{
    "id": "d9738d37-48a8-4605-...",
    "installedAppId": "b5ccfb08-d26d-4e03-...",
    "sourceType": "DEVICE_HEALTH",
    "deviceHealth": {
        "deviceIds": [],
        "subscriptionName": "healthEventHandler",
        "locationId": "0b018721-6bc0-483c-..."
    }
}

I got health update events of the devices in my location. Are you using the scopes of r:devices:* and r:locations:*?

sandra-nestor · December 23, 2022, 3:32pm

I think that the problem is in locationId. Devices’ location and the location of installed app could be different, that’s why I receive 403 response when trying to subscribe to device health using locationId. And that’s why I don’t receive events from my health subscription when subscribing using deviceIds.

I’ll try to debug this and create a health subscription using locationId. Hope, this will help me) I’ll share my success with you.

sandra-nestor · February 3, 2023, 8:45am

Hi @nayelyz! Could you please share the script you used to subscribe to the device health events? And could you specify the version of SDK you are using? Is it smartapp-sdk-nodejs version 4.0.0?

Also, I’ve managed to create a subscription to device health using deviceIds, but not locationId. I think that the reason why I receive 403 error for locationId is the problem with auth_token provided by INSTALL lifecycle. It just seems to me that it does not have “r:locations:*” scope. But when creating an app I select all possible scopes:

nayelyz · February 3, 2023, 11:40pm

Hi, @sandra-nestor!
Did you include the scope in the SmartApp’s definition? That might be the difference.
When we select them in the Dev Workspace, we’re only whitelisting them but not using them directly. The SmartApp definition I used to create a location health subscription is:

app.enableEventLogging().appId("location-room-request")
.permissions([
    "r:locations:*","r:devices:*"
])
.page('mainPage', (context, page, configData) => {
    page.section('sensors', section => {
        //This section doesn't affect the location subscription
    });
})
.updated(async (context, updateData) => {
    await context.api.subscriptions.unsubscribeAll();
    return Promise.all([
        context.api.subscriptions.subscribeToDeviceHealth('healthEventHandler')
    ])
})
.subscribedDeviceHealthEventHandler('healthEventHandler', (context, deviceEvent) => {
    console.log('health event',deviceEvent)
})

sandra-nestor · February 15, 2023, 2:41pm

Hi, @nayelyz! Thank you so much for your support! One more question. I wasn’t able to find a way how to set up additional permissions for a certain installed app using this doc. Is there a way to define these permissions like you did it here:

.permissions([
    "r:locations:*","r:devices:*"
])

via SmartThings API?

nayelyz · February 15, 2023, 10:05pm

For the SmartApp, if you registered it using the Developer Workspace, you only need to select them there to whitelist them.
However, you can change them through the API as well. I suggest you do this carefully as any change you make through the API won’t be shown in the Dev WS.

To do that, you need to follow these steps:

First need to get the Oauth config from the app and copy the result from that query:
Apps endoint > GET OAuth config
Paste that config into the body of a PUT request to the same endpoint, remember you need to add the redirectURL. For example:

{
    "clientName": "TestSmartApp2023",
    "scope": [
        "r:devices:*",
        "r:locations:*",
        "w:devices:*",
        "x:devices:*"
    ],
    "redirectUris": [
        "https://domain.com"
    ]
}

Send device health info through webhook endpoint

Customers

Developers

Download the SmartThings App