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 reference for the lifecycle phases and the API you must implement in your SmartApp.

PING

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"
  }
}



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. Detailed documentation can be found here.

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, as documented here.


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": "f01894ce-013a-434a-b51e-f82126fd72e4",
    "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": "f01894ce-013a-434a-b51e-f82126fd72e4",
    "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 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": {}
}