Skip to main content
DocsSmartThings APIEnterprise API
Docs

Scenarios

This section provides a step-by-step walkthrough of common scenarios you might encounter when using the Enterprise Eventing API.

Basic Scenario: Receiving All Events​

In this scenario, you want to receive all SmartThings events for your account - a "firehose" of all device, location, and other activity.

Prerequisites​

  • Service Account Access Token: You need a Service Account with the appropriate role (typically ACCOUNT_ADMIN). See Authorization for details on setting up Service Accounts and obtaining an access token.
  • Account ID: The ID of the account you want to receive events for.
  • Webhook Endpoint: A publicly accessible HTTPS endpoint that is ready to receive POST requests from SmartThings. See Sink Verification for details on setting up and verifying your webhook.

Step 1: Create an Event Sink​

First, create a sink to define where events should be sent.

Request:

curl -X POST \
  'https://enterprise.smartthings.com/accounts/{accountId}/sinks' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/vnd.smartthings+json;v=2' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "All-Events-Webhook",
    "description": "Receives all SmartThings events for processing.",
    "target": {
      "type": "WEBHOOK",
      "webhook": {
        "url": "https://your-webhook-url.com/events",
        "authentication": {
          "type": "NONE"
        }
      }
    }
  }'

Response:

You will receive a sinkId in the response. Keep this ID for the next step.

{
  "sinkId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "All-Events-Webhook",
  "description": "Receives all SmartThings events for processing.",
  "target": { ... }
}

Step 2: Create a Subscription​

Next, create a subscription to receive all event types without any filtering.

Request:

curl -X POST \
  'https://enterprise.smartthings.com/accounts/{accountId}/subscriptions' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Accept: application/vnd.smartthings+json;v=2' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "All-Events-Subscription",
    "description": "Subscribes to all events across the account.",
    "sinkId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "filter": {
      "type": "EVENT",
      "eventFilter": {
        "eventTypes": ["ALL"]
      }
    }
  }'

Response:

You will receive a subscriptionId in the response, confirming the subscription is active.

{
  "subscriptionId": "fedcba09-8765-4321-0987-654321fedcba",
  "name": "All-Events-Subscription",
  ...
}

Step 3: Receive Events​

Your webhook will now receive POST requests containing batches of events. Each request contains 1 to many events:

{
  "notificationType": "EVENT",
  "version": "2",
  "eventNotification": {
    "events": [
      {
        "eventTime": "2025-01-15T10:30:00Z",
        "eventType": "DEVICE_EVENT",
        "deviceEvent": {
          "eventId": "736e3903-001c-4d40-b408-ff40d162a06b",
          "locationId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
          "componentId": "main",
          "capability": "switch",
          "attribute": "switch",
          "value": "on",
          "stateChange": true
        }
      },
      {
        "eventTime": "2025-01-15T10:30:05Z",
        "eventType": "DEVICE_HEALTH_EVENT",
        "deviceHealthEvent": {
          "eventId": "f28cdef9-675a-4a10-85cd-33d512fbdccf",
          "locationId": "499e28ba-b33b-49c9-a5a1-cce40e41f8a6",
          "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
          "status": "ONLINE"
        }
      }
    ]
  }
}
note

Your webhook must handle batches of events. Always iterate through the eventNotification.events array, even if it contains only a single event.

That's it! You're now receiving all SmartThings events for your account.