Skip to main content

​
Device Connection Events

​
device.connected

Triggered when a device is successfully connected to your account. 
{
  "event": "device.connected",
  "eventId": "evt_abc123",
  "timestamp": "2025-01-23T10:30:00.000Z",
  "data": {
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "vendor": "tesla",
    "userId": "user_xyz789",
    "connectedAt": "2025-01-23T10:30:00.000Z"
  }
}

​
device.disconnected

Triggered when a device is disconnected from your account (e.g., user revokes access). 
{
  "event": "device.disconnected",
  "eventId": "evt_def456",
  "timestamp": "2025-01-23T11:00:00.000Z",
  "data": {
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "vendor": "tesla",
    "userId": "user_xyz789",
    "disconnectedAt": "2025-01-23T11:00:00.000Z",
    "reason": "user_revoked"
  }
}

​
device.reconnected

Triggered when a previously disconnected device is reconnected. 
{
  "event": "device.reconnected",
  "eventId": "evt_ghi789",
  "timestamp": "2025-01-23T12:00:00.000Z",
  "data": {
    "deviceId": "device_abc123",
    "deviceType": "battery",
    "vendor": "tesla",
    "userId": "user_xyz789",
    "reconnectedAt": "2025-01-23T12:00:00.000Z"
  }
}

​
Action Events

Webhooks are only sent for actions that reach a terminal state (completed or failed). When an action is first created, it starts in the acknowledged state, but no webhook is sent at that time. You can check the action status by polling the API (e.g., GET /hvac/actions/{actionId}), but webhooks are only delivered when the action completes or fails.

​
push.completed

Triggered when an action completes successfully. This webhook is only sent when the action reaches the completed terminal state. 
{
  "event": "push.completed",
  "eventId": "evt_mno345",
  "timestamp": "2025-01-23T10:30:05.000Z",
  "data": {
    "actionId": "act_abc123",
    "deviceId": "device_xyz789",
    "actionType": "set_permanent_hold",
    "parameters": {
      "mode": "auto",
      "heatSetpoint": 68,
      "coolSetpoint": 76
    },
    "result": {
      "success": true,
      "message": "Command executed successfully"
    },
    "completedAt": "2025-01-23T10:30:05.000Z"
  }
}

​
push.failed

Triggered when an action fails to complete. This webhook is only sent when the action reaches the failed terminal state. 
{
  "event": "push.failed",
  "eventId": "evt_pqr678",
  "timestamp": "2025-01-23T10:30:05.000Z",
  "data": {
    "actionId": "act_abc123",
    "deviceId": "device_xyz789",
    "actionType": "set_permanent_hold",
    "parameters": {
      "mode": "auto",
      "heatSetpoint": 68,
      "coolSetpoint": 76
    },
    "error": {
      "code": "DEVICE_OFFLINE",
      "message": "Device is currently offline"
    },
    "failedAt": "2025-01-23T10:30:05.000Z"
  }
}

​
Action States

When you send a push command via the API, the action goes through the following states:
  1. acknowledged - The action has been created and acknowledged. No webhook is sent at this stage. You can poll the API to check if an action is still in acknowledged state.
  2. completed - The action completed successfully. A push.completed webhook is sent.
  3. failed - The action failed to complete. A push.failed webhook is sent.
To check the status of an action while it’s still processing, use the action polling endpoint (e.g., GET /hvac/actions/{actionId}). Webhooks are only sent for terminal states (completed or failed).

​
Common Error Codes

​
DEVICE_OFFLINE
string
Device is currently offline and cannot receive commands
​
COMMAND_NOT_SUPPORTED
string
The requested command is not supported by this device model
​
TIMEOUT
string
The command timed out waiting for device response
​
RATE_LIMITED
string
Too many commands sent to the device in a short period
​
AUTHENTICATION_FAILED
string
Authentication with the OEM failed

​
Webhook Payload Fields

​
event
string
required
The webhook event type. Currently only push.completed and push.failed are sent.
​
eventId
string
required
Unique identifier for this webhook delivery. Use this for idempotency.
​
timestamp
string
required
ISO 8601 timestamp when the webhook was sent
​
data
object
required
Event-specific data payload

​
Handling Webhooks

​
Idempotency

Always use eventId to prevent processing duplicate webhooks: 
// Example: Store processed eventIds
const processedEvents = new Set();

function handleWebhook(webhook) {
  if (processedEvents.has(webhook.eventId)) {
    return; // Already processed
  }
  
  // Process webhook
  processEvent(webhook);
  
  // Mark as processed
  processedEvents.add(webhook.eventId);
}

​
Response Requirements

Your webhook endpoint must:
  • Return 200 OK for successful processing
  • Respond within 30 seconds
  • Handle duplicate deliveries gracefully

​
Next Steps

Webhook Overview

Learn about webhook setup

Security

Verify webhook signatures