Subscribe to Events

Event subscriptions tell the SmartThings platform to send your app webhook notifications when device attributes change. Without subscriptions, your app would need to poll the API to detect state changes.

Subscriptions are scoped to an installed app and are managed through the installed app's subscriptions endpoint:

https://api.smartthings.com/v1/installedapps/{installedAppId}/subscriptions

The following subscriptions are available:

Subscription Type	Scope required
DEVICE	r:devices:$deviceId
CAPABILITY	r:devices:*
MODE	r:locations:$locationId or r:locations:*
DEVICE_LIFECYCLE	r:devices:$deviceId or r:devices:*
DEVICE_HEALTH	r:devices:$deviceId or r:devices:*
SECURITY_ARM_STATE	r:security:locations:$locationId:armstate or r:security:locations:*:armstate
HUB_HEALTH	r:hubs
SCENE_LIFECYCLE	r:scenes:*

Delete Existing Subscriptions

When an existing user re-authorizes your app or you need to significantly update your subscription configuration, you may want to delete any existing subscriptions to start with a clean slate.

Avoid making this deletion a default step for every authorization flow. Unnecessary calls to the delete endpoint on a new installation are inefficient. Instead, conditionally perform this cleanup only when your database indicates the installation already exists. Alternatively, catch and handle any exceptions that occur if a duplicate subscription creation fails.

Looking to remove a single subscription?

To delete an individual subscription instead of clearing the slate, issue a DELETE request to:

https://api.smartthings.com/v1/installedapps/{installedAppId}/subscriptions/{subscriptionId}

Request

DELETE https://api.smartthings.com/v1/installedapps/{installedAppId}/subscriptions HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "count": 0
}

The count field indicates how many subscriptions were deleted. A value of 0 means there were no existing subscriptions.

Create a Capability Subscription

Create a subscription to receive events whenever a specific capability attribute changes on any device in the location. The following example subscribes to all switch attribute changes on devices with the switch capability.

Request

POST https://api.smartthings.com/v1/installedapps/{installedAppId}/subscriptions HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

{
 "sourceType": "CAPABILITY",
 "capability": {
   "locationId": "95efee9b-6073-4871-b5ba-de6642187293",
   "capability": "switch",
   "attribute": "switch",
   "stateChangeOnly": true,
   "subscriptionName": "switchHandler",
   "value": "*"
 }
}

Request Body Fields

Field	Description
sourceType	The type of event source. Use CAPABILITY to subscribe to capability attribute changes.
capability.locationId	The location to scope this subscription to
capability.capability	The capability to subscribe to (e.g. switch, switchLevel, colorControl)
capability.attribute	The specific attribute of the capability to monitor (e.g. switch for on/off state)
capability.stateChangeOnly	When true, events are only sent when the value actually changes, not on every report
capability.subscriptionName	A name you assign to this subscription. This name is included in webhook event payloads so your app can route events to the appropriate handler.
capability.value	Filter for specific values, or "*" to receive events for all values

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "id": "65ad74f8-5038-48be-a985-1b6c1c9054eb",
 "installedAppId": "b4c71ab2-116d-4d79-9125-b1909fa9b0c7",
 "sourceType": "CAPABILITY",
 "capability": {
   "locationId": "95efee9b-6073-4871-b5ba-de6642187293",
   "capability": "switch",
   "attribute": "switch",
   "value": "*",
   "stateChangeOnly": true,
   "subscriptionName": "switchHandler",
   "modes": []
 }
}

Response Fields

Field	Description
id	Unique identifier for the created subscription
installedAppId	The installed app this subscription belongs to
sourceType	Confirms the subscription type
capability	Echo of the subscription configuration
capability.modes	Location modes that this subscription is active for (empty means all modes)

Create a Subscription for a Specific Device

Create a subscription to receive events whenever any capability attribute changes on a specific device.

Request

POST https://api.smartthings.com/v1/installedapps/{installedAppId}/subscriptions HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

{
  "sourceType": "DEVICE",
  "device": {
    "deviceId": "e16098f0-08bd-4ecb-aecb-9f30902bb618"
  },
  "subscriptionName": "deviceHandler"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "8e1877cb-7e44-4bad-87ad-9dc2ac30ac53",
  "installedAppId": "059da7c5-7c0b-4cd7-ab91-922e15e7e284",
  "sourceType": "DEVICE",
  "device": {
    "deviceId": "e16098f0-08bd-4ecb-aecb-9f30902bb618",
    "componentId": "*",
    "capability": "*",
    "attribute": "*",
    "value": "*",
    "stateChangeOnly": true,
    "modes": []
  }
}

How Events Are Delivered

Once a subscription is active, SmartThings sends POST requests to your app's webhook endpoint (POST /) whenever a matching event occurs. For example, when any switch in the subscribed location turns on or off, your app receives a device event with the subscriptionName you specified (e.g. switchHandler).

See Webhook Events for the full event payload structure.

Up Next

Visit Webhook Events to learn how SmartThings securely delivers events to your webhook endpoint once your subscriptions are active. We'll cover how to verify request authenticity using HTTP signatures, parse incoming device state changes, and properly handle app lifecycle events like uninstallations.