Skip to main content
DocsSmartThings APIEnterprise API
Docs

Event Types

This page provides detailed payload structures for each event type delivered through Enterprise Eventing. All events share a common wrapper structure with event-specific fields.

Common Event Structure​

Every event delivered to your sink follows this top-level structure:

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "DEVICE_EVENT",
  "version": "2",
  "[eventType]": {
    // Event-specific payload
  }
}

Common fields:

  • accountId - The enterprise account ID
  • notificationType - The type of event (matches one of the event types below)
  • version - Event schema version (currently "2")
  • [eventType] - Field name matches the notification type in camelCase (e.g., deviceEvent, deviceLifecycleEvent)

Device Events​

Notification Type: DEVICE_EVENT

Device events are triggered when a device's capability attribute changes (e.g., a switch turns on, temperature reading updates).

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "DEVICE_EVENT",
  "version": "2",
  "deviceEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "ownerType": "LOCATION",
    "ownerId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "deviceId": "736e3903-001c-4d40-b408-ff40d162a06b",
    "componentId": "main",
    "capability": "switch",
    "attribute": "switch",
    "value": "on",
    "valueType": "string",
    "stateChange": true,
    "commandId": "cmd-123",
    "data": {},
    "sensitive": false,
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • locationId - Location where the device resides
  • ownerType - Type of owner (e.g., "LOCATION")
  • ownerId - ID of the owner
  • deviceId - The device that triggered the event
  • componentId - Component on the device (typically "main")
  • capability - Capability name (e.g., "switch", "temperatureMeasurement")
  • attribute - Attribute that changed (e.g., "switch", "temperature")
  • value - New value of the attribute (can be string, number, object, or array)
  • valueType - Type of the value: "string", "number", "object", "array"
  • stateChange - Whether this represents an actual state change (true) or just a report (false)
  • commandId - ID of the command that triggered this event (if applicable)
  • data - Additional data associated with the event
  • sensitive - Whether the event contains sensitive data
  • unit - Unit of measurement (optional, only for certain capabilities like temperature)
  • timestamp - ISO 8601 timestamp when the event occurred

Device Lifecycle Events​

Notification Type: DEVICE_LIFECYCLE_EVENT

Device lifecycle events track when devices are created, updated, deleted, or moved between locations/rooms.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "DEVICE_LIFECYCLE_EVENT",
  "version": "2",
  "deviceLifecycleEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "ownerType": "LOCATION",
    "ownerId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "deviceId": "736e3903-001c-4d40-b408-ff40d162a06b",
    "deviceName": "Living Room Light",
    "principal": "user-uuid-123",
    "lifecycle": "CREATE",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • locationId - Location where the event occurred
  • ownerType - Type of owner (e.g., "LOCATION")
  • ownerId - ID of the owner
  • deviceId - The device affected
  • deviceName - Name of the device
  • principal - User or entity that initiated the lifecycle change
  • lifecycle - Lifecycle action: CREATE, UPDATE, DELETE, MOVE_FROM, MOVE_TO, ROOM_MOVE
  • timestamp - ISO 8601 timestamp

Device Health Events​

Notification Type: DEVICE_HEALTH_EVENT

Device health events indicate changes in a device's connectivity status.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "DEVICE_HEALTH_EVENT",
  "version": "2",
  "deviceHealthEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "ownerType": "LOCATION",
    "ownerId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "deviceId": "736e3903-001c-4d40-b408-ff40d162a06b",
    "hubId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "status": "ONLINE",
    "reason": "NONE",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • locationId - Location where the device resides
  • ownerType - Type of owner (e.g., "LOCATION")
  • ownerId - ID of the owner
  • deviceId - The device whose health changed
  • hubId - Hub managing the device (if applicable)
  • status - Health status: ONLINE, OFFLINE, UNHEALTHY
  • reason - Reason for offline status: NONE, HUB_OFFLINE, ZIGBEE_OFFLINE, ZWAVE_OFFLINE, BLUETOOTH_OFFLINE, HUB_DISCONNECTED, SERVICE_UNAVAILABLE
  • eventSource - Source of the event (optional)
  • timestamp - ISO 8601 timestamp

Hub Lifecycle Events​

Notification Type: HUB_LIFECYCLE_EVENT

Hub lifecycle events track when hubs are created, updated, or deleted.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "HUB_LIFECYCLE_EVENT",
  "version": "2",
  "hubLifecycleEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "lifecycle": "CREATE",
    "hubId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • lifecycle - Lifecycle action: CREATE, UPDATE, DELETE
  • hubId - The hub affected
  • locationId - Location where the hub resides
  • timestamp - ISO 8601 timestamp

Hub Health Events​

Notification Type: HUB_HEALTH_EVENT

Hub health events indicate changes in a hub's connectivity status.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "HUB_HEALTH_EVENT",
  "version": "2",
  "hubHealthEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "hubId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "status": "ONLINE",
    "reason": "NONE",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • hubId - The hub whose health changed
  • locationId - Location where the hub resides
  • status - Health status: ONLINE, OFFLINE
  • reason - Reason for offline status: NONE, SERVICE_UNAVAILABLE
  • timestamp - ISO 8601 timestamp

Location Lifecycle Events​

Notification Type: LOCATION_LIFECYCLE_EVENT

Location lifecycle events track when locations are created, updated, or deleted.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "LOCATION_LIFECYCLE_EVENT",
  "version": "2",
  "locationLifecycleEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "lifecycle": "CREATE",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • lifecycle - Lifecycle action: CREATE, UPDATE, DELETE
  • locationId - The location affected
  • timestamp - ISO 8601 timestamp

Mode Events​

Notification Type: MODE_EVENT

Mode events are triggered when a location's mode changes.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "MODE_EVENT",
  "version": "2",
  "modeEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "modeId": "550e8400-e29b-41d4-a716-446655440001",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • locationId - Location where the mode changed
  • modeId - The new mode ID
  • timestamp - ISO 8601 timestamp

Scene Lifecycle Events​

Notification Type: SCENE_LIFECYCLE_EVENT

Scene lifecycle events track when scenes are created, updated, or deleted.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "SCENE_LIFECYCLE_EVENT",
  "version": "2",
  "sceneLifecycleEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "sceneId": "550e8400-e29b-41d4-a716-446655440002",
    "lifecycle": "CREATE",
    "version": "1",
    "migrateUuid": "",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • locationId - Location where the scene resides
  • sceneId - The scene affected
  • lifecycle - Lifecycle action: CREATE, UPDATE, DELETE, CREATEFORBIXBY, UPDATEFORBIXBY, DELETEFORBIXBY
  • version - Version of the scene
  • migrateUuid - Migration UUID (if applicable)
  • timestamp - ISO 8601 timestamp

Installed App Lifecycle Events​

Notification Type: INSTALLED_APP_LIFECYCLE_EVENT

Installed app lifecycle events track when apps are installed, updated, or uninstalled.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "INSTALLED_APP_LIFECYCLE_EVENT",
  "version": "2",
  "installedAppLifecycleEvent": {
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "installedAppId": "550e8400-e29b-41d4-a716-446655440003",
    "appId": "a1b2c3d4-5678-90ab-cdef-app000000001",
    "lifecycle": "INSTALL",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • locationId - Location where the app is installed
  • installedAppId - The installed app instance ID
  • appId - The app definition ID
  • lifecycle - Lifecycle action: CREATE, INSTALL, UPDATE, DELETE, OTHER
  • timestamp - ISO 8601 timestamp

Appliance Diagnostic Events​

Notification Type: APPLIANCE_DIAGNOSTIC_EVENT

Appliance diagnostic events provide diagnostic information from Samsung appliances.

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "APPLIANCE_DIAGNOSTIC_EVENT",
  "version": "2",
  "applianceDiagnosticEvent": {
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
    "locationId": "76fa4215-f9f5-4532-897e-5207db0da124",
    "deviceId": "736e3903-001c-4d40-b408-ff40d162a06b",
    "architectureType": "microwave",
    "deviceType": "oven",
    "deviceEventTime": "2025-01-15T10:30:00Z",
    "errorCode": "C-21",
    "deviceModelCode": "DW80R9950US/AA",
    "deviceSerialNumber": "0HZB8DDN50A387D",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

Fields:

  • eventId - Unique identifier for this event
  • locationId - Location where the appliance resides
  • deviceId - The appliance device
  • architectureType - Architecture type of the appliance (e.g., "microwave", "refrigerator")
  • deviceType - Device type of the appliance (e.g., "oven", "washer")
  • deviceEventTime - ISO 8601 timestamp when the diagnostic event occurred on the device
  • errorCode - Manufacturer-specific error/diagnostic code
  • deviceModelCode - Model code of the appliance
  • deviceSerialNumber - Serial number of the appliance
  • timestamp - ISO 8601 timestamp when the event was processed by SmartThings
note

Appliance diagnostic events are specific to Samsung smart appliances and may contain manufacturer-specific diagnostic codes and data structures.