Scenarios

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

For guidance on how to structure your sinks, subscriptions, and filters to maximize coverage within the default quotas, see the Subscription Design Guide.

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.