Overview

Enterprise Eventing provides a scalable, account-level event delivery system for enterprise applications. Service accounts can configure webhook receivers for all devices and locations across an entire enterprise account, enabling real-time monitoring and integration at scale.

What is Enterprise Eventing?

Enterprise Eventing consists of three main components:

Sinks - Webhook endpoints that receive events
Subscriptions - Filter configurations that determine which events are delivered
Events - Real-time notifications about device state changes, lifecycle events, and more

Key Features:

Account-wide scope - Receive events for all devices and locations in your enterprise account
Service account authorization - Use service account tokens for programmatic access
Automatic device inclusion - All devices in the account are automatically included
Flexible filtering - Filter events by capability, event type, or location group
Enterprise scale - Designed for fleet management and multi-property monitoring

Use Cases

Enterprise Eventing is designed for:

✅ Real-time Monitoring - Track device status across multiple properties

✅ Fleet Management - Monitor large deployments of devices

✅ External System Integration - Send device data to analytics platforms, databases, or business intelligence tools

✅ Audit Trails - Log all device lifecycle events for compliance

✅ Predictive Maintenance - Analyze device health events across your fleet

Sinks

API Reference

A sink is a webhook endpoint that receives events. Sinks are registered at the account level and can be reused across multiple subscriptions.

Creating a Sink

To create a sink, make a POST request to /accounts/{accountId}/sinks:

{
  "name": "My-Webhook-Endpoint",
  "type": "HTTPS_SINK",
  "httpsSink": {
    "endpoint": "https://example.com/webhook"
  }
}

Required fields:

name - A descriptive name for the sink (cannot contain spaces).
type - Must be HTTPS_SINK
httpsSink.endpoint - HTTPS URL for your webhook (HTTP not supported)

Response:

{
  "sinkId": "7de9a66a-8be6-4b69-9543-92ab3058bd6d",
  "name": "My-Webhook-Endpoint",
  "type": "HTTPS_SINK",
  "httpsSink": {
    "endpoint": "https://example.com/webhook"
  },
  "status": "REGISTERED",
  "createdDate": "2025-01-15T10:30:00Z",
  "lastUpdatedDate": "2025-01-15T10:30:00Z"
}

Sink Verification

When you create a sink, SmartThings sends a verification challenge to your webhook endpoint:

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "SINK_CONFIRMATION",
  "version": "2",
  "sinkConfirmationNotification": {
    "sinkId": "7de9a66a-8be6-4b69-9543-92ab3058bd6d",
    "challenge": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Your endpoint must respond with 200 OK and return the challenge:

{
  "challenge": "550e8400-e29b-41d4-a716-446655440000"
}

warning

You cannot delete a sink that has active subscriptions. You must first delete all subscriptions associated with the sink before the sink can be deleted. Note that due to eventual consistency, there may be a brief delay between deleting a subscription and being able to delete its sink.

Subscriptions

API Reference

A subscription links a sink to specific events using filters. Subscriptions determine which events are delivered to your webhook.

Creating a Subscription

To create a subscription, make a POST request to /accounts/{accountId}/subscriptions:

{
  "name": "Device-Lifecycle-Events",
  "sinkId": "7de9a66a-8be6-4b69-9543-92ab3058bd6d",
  "scope": "ACCOUNT",
  "filters": [
    {
      "type": "EVENT",
      "eventFilter": {
        "eventTypes": ["DEVICE_LIFECYCLE_EVENT", "LOCATION_LIFECYCLE_EVENT"]
      }
    }
  ]
}

Required fields:

name - A descriptive name for the subscription (cannot contain spaces).
sinkId - The ID of the sink to deliver events to
filters - Array of filter configurations (at least one required)

Optional fields:

scope - Either ACCOUNT (default) or LOCATION_GROUP
scopeId - Required if scope is LOCATION_GROUP, must be a valid location group ID
description - Optional description

Filters

Filters determine which events are delivered to your sink. You can use two types of filters:

EVENT Filter

Subscribe to specific event types:

{
  "type": "EVENT",
  "eventFilter": {
    "eventTypes": ["DEVICE_LIFECYCLE_EVENT", "DEVICE_HEALTH_EVENT", "LOCATION_LIFECYCLE_EVENT"]
  }
}

Available event types:

APPLIANCE_DIAGNOSTIC_EVENT - Samsung appliance diagnostic events
DEVICE_EVENT - Device capability/attribute changes
DEVICE_HEALTH_EVENT - Device online/offline status
DEVICE_LIFECYCLE_EVENT - Device created, updated, deleted, moved
HUB_HEALTH_EVENT - Hub health status
HUB_LIFECYCLE_EVENT - Hub lifecycle changes
INSTALLED_APP_LIFECYCLE_EVENT - Installed app lifecycle
LOCATION_LIFECYCLE_EVENT - Location created, updated, deleted
MODE_EVENT - Mode changes
SCENE_LIFECYCLE_EVENT - Scene lifecycle changes

CAPABILITY Filter

Subscribe to device events for specific capabilities:

{
  "type": "CAPABILITY",
  "capabilityFilter": {
    "capabilities": [
      {
        "capability": "switch",
        "attribute": "switch",
        "component": "main"
      },
      {
        "capability": "temperatureMeasurement",
        "attribute": "*",
        "component": "*"
      }
    ],
    "exclude": false
  }
}

Capability filter fields:

capability - The capability name (required)
attribute - Specific attribute or * for all (optional, defaults to *)
component - Specific component or * for all (optional, defaults to *)
exclude - If true, delivers all device events EXCEPT those matching the specified capabilities. If false, delivers only events matching the specified capabilities (default: false)

Multiple capability items: Multiple items in the capabilities array use OR logic:

When exclude: false - Events matching ANY capability item will be delivered
When exclude: true - Events matching ANY capability item will be excluded (only events that don't match any item will be delivered)

Combining Filters

You can include multiple filters in a subscription. Each filter type can only appear once:

{
  "filters": [
    {
      "type": "EVENT",
      "eventFilter": {
        "eventTypes": ["LOCATION_LIFECYCLE_EVENT"]
      }
    },
    {
      "type": "CAPABILITY",
      "capabilityFilter": {
        "capabilities": [
          {
            "capability": "switch"
          }
        ]
      }
    }
  ]
}

warning

You cannot combine a CAPABILITY filter with an EVENT filter containing ALL or DEVICE_EVENT event types, as this would create ambiguous filtering logic.

Receiving Events

When subscribed events occur, SmartThings sends a POST request to your sink's webhook endpoint with a batch of events.

Event Payload Structure

Webhook deliveries use a consistent structure with batched events:

{
  "accountId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "notificationType": "EVENT",
  "version": "2",
  "eventNotification": {
    "locationGroupId": "43e807f6-f668-46d4-a97f-06998dcf748d",
    "events": [
      {
        "eventTime": "2025-04-28T12:39:37Z",
        "eventType": "DEVICE_EVENT",
        "deviceEvent": {
          "eventId": "736e3903-001c-4d40-b408-ff40d162a06b",
          "locationId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "ownerType": "LOCATION",
          "ownerId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
          "componentId": "main",
          "capability": "motionSensor",
          "attribute": "motion",
          "value": "active",
          "valueType": "string",
          "stateChange": true,
          "data": {},
          "commandId": "cmd-123",
          "sensitive": false
        }
      },
      {
        "eventTime": "2025-04-28T12:39:38Z",
        "eventType": "DEVICE_HEALTH_EVENT",
        "deviceHealthEvent": {
          "eventId": "f28cdef9-675a-4a10-85cd-33d512fbdccf",
          "locationId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "ownerType": "LOCATION",
          "ownerId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
          "hubId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "status": "OFFLINE",
          "reason": "HUB_OFFLINE",
          "eventSource": "OCFDEVICE"
        }
      },
      {
        "eventTime": "2025-04-28T12:39:39Z",
        "eventType": "HUB_HEALTH_EVENT",
        "hubHealthEvent": {
          "eventId": "a1aef8ee-9b11-4d5a-b44c-3e51d583c518",
          "locationId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "hubId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "status": "OFFLINE",
          "reason": "SERVICE_UNAVAILABLE"
        }
      }
    ]
  }
}

Top-level fields:

accountId - The account ID the events belong to
notificationType - Always "EVENT" for platform event deliveries (or "SINK_CONFIRMATION" for webhook verification)
version - Event schema version (currently "2")
eventNotification - Container for the event batch

Event notification fields:

locationGroupId - The location group where the events originated
events - Array of events (typically batched together by proximity in time)

Individual event fields:

Each event in the events array contains:

eventTime - ISO 8601 timestamp when the event occurred
eventType - Type of event (e.g., DEVICE_EVENT, DEVICE_LIFECYCLE_EVENT, HUB_HEALTH_EVENT)
[eventType] - Field matching the event type with event-specific data (e.g., deviceEvent, deviceHealthEvent)

Batch Delivery Behavior

SmartThings batches events that occur close together in time to reduce webhook traffic. This means:

A single POST request may contain 1 to many events in the events array
All events in a batch must share the same locationGroupId (single field at the notification level)
Events in a batch may have different eventType values (e.g., DEVICE_EVENT, DEVICE_HEALTH_EVENT, HUB_HEALTH_EVENT)
Each event has its own eventTime and eventType
Your webhook must process all events in the array

tip

See the Event Types page for detailed payload structures for each event type within the events array.

Webhook Requirements

Your webhook endpoint must:

Accept POST requests
Use HTTPS (HTTP not supported)
Respond with 2xx status code within the timeout period
Be idempotent (in rare cases, the same event may be delivered more than once)

tip

See the Authorization page for details on webhook authentication and security.

API Reference

For complete API documentation, see:

Account Sinks API

Account Subscriptions API

What is Enterprise Eventing?​

Use Cases​

Sinks​

Creating a Sink​

Sink Verification​

Subscriptions​

Creating a Subscription​

Filters​

EVENT Filter​

CAPABILITY Filter​

Combining Filters​

Receiving Events​

Event Payload Structure​

Batch Delivery Behavior​

Webhook Requirements​

API Reference​

What is Enterprise Eventing?

Use Cases

Sinks

Creating a Sink

Sink Verification

Subscriptions

Creating a Subscription

Filters

EVENT Filter

CAPABILITY Filter

Combining Filters

Receiving Events

Event Payload Structure

Batch Delivery Behavior

Webhook Requirements

API Reference