Skip to main content

Lifecycles

SmartThings will issue a POST request to SmartApps during various lifecycle phases. The request body will contain the lifecycle that triggered the execution, along with other data depending on the specific lifecycle phase.

See the SmartApp API endpoint documentation for the lifecycle phases and the API you must implement in your SmartApp.

CONFIRMATION​

The CONFIRMATION lifecycle phase occurs when a webhook SmartApp is registered.

This lifecycle phase is used to verify ownership of the target url specified when you created your webhook SmartApp.

CONFIRMATION request body​

{
  "lifecycle": "CONFIRMATION",
  "executionId": "8F8FA33E-2A5B-4BC5-826C-4B2AB73FE9DD",
  "appId": "fd9949ee-a3bf-4069-b4b3-3e9c1c922e29",
  "locale": "en",
  "version": "0.1.0",
  "confirmationData": {
    "appId": "fd9949ee-a3bf-4069-b4b3-3e9c1c922e29",
    "confirmationUrl": "{CONFIRMATION_URL}"
  },
  "settings": {}
}

CONFIRMATION response​

200 OK
{
    "targetUrl": "{TARGET_URL}"
}

CONFIGURATION​

The CONFIGURATION lifecycle phase occurs during the installation of a SmartApp. During this phase, the SmartApp defines the configuration of the installation, including the inputs required from the end user.

The CONFIGURATION lifecycle has two phases: INITIALIZE and PAGE. You can find more info in the configuration documentation.

CONFIGURATION request body​

{
  "lifecycle": "CONFIGURATION",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "configurationData": {
    "installedAppId": "string",
    "phase": "INITIALIZE",
    "pageId": "string",
    "previousPageId": "string",
    "config": {
      "property1": [
        {
          "valueType": "DEVICE",
          "deviceConfig": {
            "deviceId": "31192dc9-eb45-4d90-b606-21e9b66d8c2b",
            "componentId": "main"
          }
        }
      ],
      "property2": [
        {
          "valueType": "DEVICE",
          "deviceConfig": {
            "deviceId": "31192dc9-eb45-4d90-b606-21e9b66d8c2b",
            "componentId": "main"
          }
        }
      ]
    }
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

CONFIGURATION response​

The SmartApp must respond to the CONFIGURATION request with the data required for installation, per the configuration documentation.

INSTALL​

The INSTALL lifecycle phase occurs when the end user has successfully installed the SmartApp. It is during this lifecycle that subscriptions, schedules, or other initialization activities should occur.

INSTALL request body​

The INSTALL lifecycle phase request will contain information about the installed app, including all configuration selections and authorized permissions:

{
  "lifecycle": "INSTALL",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "installData": {
    "authToken": "string",
    "refreshToken": "string",
    "installedApp": {
      "installedAppId": "d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId": "e675a3d9-2499-406c-86dc-8a492a886494",
      "config": {
        "contactSensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
              "componentId": "main"
            }
          }
        ],
        "lightSwitch": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId": "main"
            }
          }
        ],
        "minutes": [
          {
            "valueType": "STRING",
            "stringConfig": {
              "value": "5"
            }
          }
        ],
      },
        "permissions": [
          "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
          "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
          "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
      ]
    }
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

INSTALL response​

The SmartApp should respond to the INSTALL request with a 200 status and an empty installData object:

200 OK
{
  "installData": {}
}

UPDATE​

The UPDATE lifecycle phase occurs when the end user updates an already-installed SmartApp's configuration. Any subscriptions, schedules, or other actions taken as a result of an end user's configuration should be accounted for during this lifecycle.

UPDATE request body​

The UPDATE lifecycle phase request will contain information about the installed app, including all the updated and previous configuration selections and authorized permissions:

{
  "lifecycle": "UPDATE",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "updateData": {
    "authToken": "string",
    "refreshToken": "string",
    "installedApp": {
      "installedAppId": "d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId": "e675a3d9-2499-406c-86dc-8a492a886494",
      "config": {
        "contactSensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
              "componentId": "main"
            }
          }
        ],
        "lightSwitch": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId": "main"
            }
          }
        ],
        "minutes": [
          {
            "valueType": "STRING",
            "stringConfig": {
              "value": "5"
            }
          }
        ],
      },
      "permissions": [
        "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
        "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
        "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
      ]
    },
    "previousConfig": {
      "contactSensor": [
        {
          "valueType": "DEVICE",
          "deviceConfig": {
            "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
            "componentId": "main"
          }
        }
      ],
      "lightSwitch": [
        {
          "valueType": "DEVICE",
          "deviceConfig": {
            "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
            "componentId": "main"
          }
        }
      ],
      "minutes": [
        {
          "valueType": "STRING",
          "stringConfig": {
            "value": "5"
          }
        }
      ],
    },
    "previousPermissions": [
      "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
      "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
      "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
    ]
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

UPDATE response​

The SmartApp should respond to the UPDATE request with a 200 status and an empty updateData object:

200 OK
{
  "updateData": {}
}

EVENT​

The EVENT lifecycle phase occurs when the SmartApp is executed in response to a subscribed-to device event or scheduled execution.

EVENT request body​

The EVENT lifecycle phase request will contain information about the installed app, including all configuration selections and authorized permissions, as well as information about the event that triggered the execution.

Sample device event request body:

{
  "lifecycle": "EVENT",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "eventData": {
    "authToken": "string",
    "installedApp": {
      "installedAppId": "d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId": "e675a3d9-2499-406c-86dc-8a492a886494",
      "config": {
        "contactSensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
              "componentId": "main"
            }
          }
        ],
        "lightSwitch":[
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId": "main"
            }
          }
        ],
        "minutes":[
          {
            "valueType": "STRING",
            "stringConfig": {
              "value": "5"
            }
          }
        ],
      },
      "permissions": [
        "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
        "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
        "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
      ]
    },
    "events": [
      {
        "eventType": "DEVICE_EVENT",
        "deviceEvent": {
          "subscriptionName": "motion_sensors",
          "eventId": "736e3903-001c-4d40-b408-ff40d162a06b",
          "locationId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
          "componentId": "main",
          "capability": "motionSensor",
          "attribute": "motion",
          "value" :"active",
          "stateChange": true
        }
      }
    ]
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

Sample timer event request body:

{
  "lifecycle": "EVENT",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "eventData": {
    "authToken": "string",
    "installedApp": {
      "installedAppId": "d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId": "e675a3d9-2499-406c-86dc-8a492a886494",
      "config": {
        "contactSensor": [
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "e457978e-5e37-43e6-979d-18112e12c961",
              "componentId": "main"
            }
          }
        ],
        "lightSwitch":[
          {
            "valueType": "DEVICE",
            "deviceConfig": {
              "deviceId": "74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId": "main"
            }
          }
        ],
        "minutes":[
          {
            "valueType": "STRING",
            "stringConfig": {
              "value": "5"
            }
          }
        ],
      },
      "permissions": [
        "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
        "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
        "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
      ]
    },
    "events": [
      {
        "eventType": "TIMER_EVENT",
        "timerEvent": {
          "eventId": "string",
          "name": "lights_off_timeout",
          "type": "CRON",
          "time": "2017-09-13T04:18:12.469Z",
          "expression": "string"
        }
      }
    ]
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

EVENT response​

The SmartApp should respond to the EVENT request with a 200 status and an empty eventData object:

200 OK
{
  "eventData": {}
}

OAUTH_CALLBACK​

The OAUTH_CALLBACK lifecycle phase occurs when a third-party cloud responds to an OAuth authentication request by the SmartApp.

OAUTH_CALLBACK request body​

The SmartApp is called with a relative URL that contains all the query string parameters as returned by the third party OAuth system. The SmartApp is expected to extract all the sensitive authorization codes and tokens, and use them to access the third-party system.

Sample request body:


{
  "lifecycle": "OAUTH_CALLBACK",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "oAuthCallbackData": {
    "installedAppId": "string",
    "urlPath": "string"
  },
}

OAUTH_CALLBACK response​

The SmartApp should respond to the OAUTH_CALLBACK request with a 200 status and an empty oAuthCallbackData object:


200 OK
{
"oAuthCallbackData": { }
}

UNINSTALL​

The UNINSTALL lifecycle phase occurs when the SmartApp is uninstalled by the end user. Any cleanup tasks that the SmartApp requires when a user uninstalls the app should be handled during this phase.

All subscriptions and schedules for the installed app will be automatically deleted by SmartThings.

UNINSTALL request body​

{
  "lifecycle": "UNINSTALL",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "uninstallData":{
    "installedApp":{
      "installedAppId":"d692699d-e7a6-400d-a0b7-d5be96e7a564",
      "locationId":"e675a3d9-2499-406c-86dc-8a492a886494",
      "config":{
        "contactSensor":[
          {
            "valueType":"DEVICE",
            "deviceConfig":{
              "deviceId":"e457978e-5e37-43e6-979d-18112e12c961",
              "componentId":"main"
            }
          }
        ],
        "lightSwitch":[
          {
            "valueType":"DEVICE",
            "deviceConfig":{
              "deviceId":"74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
              "componentId":"main"
            }
          }
        ],
        "minutes":[
          {
            "valueType":"STRING",
            "stringConfig":{
              "value":"5"
            }
          }
        ],
      },
      "permissions":[
        "r:devices:e457978e-5e37-43e6-979d-18112e12c961",
        "r:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76",
        "x:devices:74aac3bb-91f2-4a88-8c49-ae5e0a234d76"
      ]
    }
  },
  "settings": {
    "property1": "string",
    "property2": "string"
  }
}

UNINSTALL response​

The SmartApp should respond to the UNINSTALL request with a 200 status and an empty uninstallData object:

200 OK
{
  "uninstallData": {}
}

PING​

important

This lifecycle is deprecated. New SmartApps should use the CONFIRMATION lifecycle.

The PING lifecycle phase occurs when a webhook SmartApp is registered.

The purpose of this lifecycle phase is to verify the existence and integrity of the webhook SmartApp.

PING request body​

{
  "lifecycle": "PING",
  "executionId": "b328f242-c602-4204-8d73-33c48ae180af",
  "locale": "en",
  "version": "1.0.0",
  "pingData": {
    "challenge": "1a904d57-4fab-4b15-a11e-1c4bfe7cb502"
  }
}

PING response​

SmartApps must respond to the PING request with the challenge code sent:

200 OK
{
  "pingData": {
    "challenge": "1a904d57-4fab-4b15-a11e-1c4bfe7cb502"
  }
}