VEHICLE_STATE Event

Triggered when one or more signals you’ve configured as triggers change their value. This event delivers the updated signal data for all subscribed signals in the payload.

All Configured Signals Are Always IncludedEvery VEHICLE_STATE event contains all signals you configured in your webhook subscription, regardless of which signal(s) triggered the event. This ensures you always have complete vehicle state data.Example: If your webhook subscribes to 10 signals but only 1 trigger changes, you’ll receive all 10 signals in the payload.

When This Event Fires

The VEHICLE_STATE event fires when Smartcar detects a signal value change for any trigger signal configured in your webhook.

Trigger Configuration

You configure which signals should trigger this event through the Smartcar Dashboard when creating or editing a webhook. For example: Triggers:

TractionBattery.StateOfCharge (code: tractionbattery-stateofcharge)
Charge.IsCharging (code: charge-ischarging)
Location.PreciseLocation (code: location-preciselocation)

Subscribed Signals:

TractionBattery.StateOfCharge
Charge.IsCharging
Location.PreciseLocation
Charge.Voltage
Odometer.TraveledDistance

If any of the trigger signals change, a VEHICLE_STATE event is delivered containing all five subscribed signals.

Identifying Which Triggers Fired

The webhook payload includes a triggers field that specifies which trigger signal(s) changed to prompt this delivery. This helps you identify what caused the event without comparing all signal values.

Trigger Types

Signal Change Triggers

When a monitored trigger signal changes value, the triggers array contains the signal(s) that changed.

{
  "triggers": [
    {
      "code": "tractionbattery-stateofcharge",
      "name": "StateOfCharge",
      "group": "TractionBattery"
    }
  ]
}

If multiple triggers change simultaneously, all will be included in the array.

First Delivery Trigger

When a webhook subscription is first created, a FIRST_DELIVERY trigger is sent to provide the initial state of the vehicle.

{
  "triggers": [
    {
      "code": "FIRST_DELIVERY"
    }
  ]
}

This initial delivery:

Occurs after vehicle subscription to a webhook
Contains all subscribed signals at their current values
Does not indicate any signal value changes
Helps establish baseline state for your application

When FIRST_DELIVERY is sent again:

When a vehicle is unsubscribed and then resubscribed to your webhook
If your endpoint fails to respond with a 2xx status code, Smartcar will retry delivery with the same FIRST_DELIVERY trigger

Use the triggers field to determine the delivery reason. Check for "code": "FIRST_DELIVERY" to identify initial state deliveries versus change-triggered deliveries.

Payload Structure

eventId

string

required

Unique identifier for this event. Use this for idempotency to prevent duplicate processing.

eventType

string

required

Always "VEHICLE_STATE" for this event type.

vehicleId

string

required

Smartcar vehicle ID for the vehicle this event relates to.

data

object

required

Container for event data.

Show data object

user

object

required

Information about the user who connected the vehicle.

string

Smartcar user ID

vehicle

object

required

Vehicle information

string

Smartcar vehicle ID

make

string

Vehicle manufacturer (e.g., "TESLA", "FORD", "BMW")

model

string

Vehicle model (e.g., "Model 3", "Mustang Mach-E")

year

integer

Vehicle model year

mode

string

Vehicle mode (e.g., "live")

powertrainType

string

Vehicle powertrain (e.g., "BEV")

triggers

array

required

Array of trigger signal objects that changed to prompt this delivery. Helps identify which configured triggers actually fired.

code

string

Kebab-case signal identifier (e.g., "tractionbattery-stateofcharge") or "FIRST_DELIVERY" for initial deliveries

name

string

Human-readable signal name (e.g., "StateOfCharge")

group

string

Signal category (e.g., "TractionBattery")

signals

array

required

Array of signal objects containing data for all signals configured in your webhook subscription. This array always includes every subscribed signal, even if only one trigger changed to fire this event.

code

string

Kebab-case signal identifier (e.g., "tractionbattery-stateofcharge")

name

string

Human-readable signal name (e.g., "StateOfCharge")

group

string

Signal category (e.g., "TractionBattery", "Charge", "Location")

body

object

Signal-specific data structure. See Signals Reference for complete schemas.Each signal type has a unique body structure. Common examples:

Battery state of charge: { "unit": "percent", "value": 78 }
Charging status: { "value": true }
Location: { "latitude": 37.4292, "longitude": -122.1381 }

Example Payloads

Signal Change Trigger
First Delivery

Delivered when a configured trigger signal changes value.

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "VEHICLE_STATE",
  "vehicleId": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "vehicle": {
      "id": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020,
      "mode": "live",
      "powertrainType": "BEV"
    },
    "triggers": [
      {
        "code": "tractionbattery-stateofcharge",
        "name": "StateOfCharge",
        "group": "TractionBattery"
      }
    ],
    "signals": [
      {
        "code": "tractionbattery-stateofcharge",
        "name": "StateOfCharge",
        "group": "TractionBattery",
        "body": {
          "unit": "percent",
          "value": 78
        },
        "meta": {
          "oemUpdatedAt": 1731940328000,
          "fetchedAt": 1731940330000
        }
      },
      {
        "code": "charge-ischarging",
        "name": "IsCharging",
        "group": "Charge",
        "body": {
          "value": true
        },
        "meta": {
          "oemUpdatedAt": 1731940328000,
          "fetchedAt": 1731940330000
        }
      },
      {
        "code": "charge-voltage",
        "name": "Voltage",
        "group": "Charge",
        "body": {
          "unit": "volts",
          "value": 240
        },
        "meta": {
          "oemUpdatedAt": 1731940328000,
          "fetchedAt": 1731940330000
        }
      }
    ]
  },
  "meta": {
    "version": "4.0",
    "deliveryId": "48b25f8f-9fea-42e1-9085-81043682cbb8",
    "deliveredAt": 1731940328000,
    "webhookId": "abde94ff-d57d-43b9-8d09-6020db2d977a",
    "webhookName": "Battery Monitoring",
    "signalCount": 3,
    "mode": "LIVE"
  }
}

Delivered immediately after webhook subscription creation to provide initial vehicle state.

{
  "eventId": "7c8d9e10-f2a3-4b5c-6d7e-8f9a0b1c2d3e",
  "eventType": "VEHICLE_STATE",
  "vehicleId": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "vehicle": {
      "id": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020,
      "mode": "live",
      "powertrainType": "BEV"
    },
    "triggers": [
      {
        "code": "FIRST_DELIVERY"
      }
    ],
    "signals": [
      {
        "code": "tractionbattery-stateofcharge",
        "name": "StateOfCharge",
        "group": "TractionBattery",
        "body": {
          "unit": "percent",
          "value": 65
        },
        "meta": {
          "oemUpdatedAt": 1731926100000,
          "fetchedAt": 1731926102000
        }
      },
      {
        "code": "charge-ischarging",
        "name": "IsCharging",
        "group": "Charge",
        "body": {
          "value": false
        },
        "meta": {
          "oemUpdatedAt": 1731926100000,
          "fetchedAt": 1731926102000
        }
      },
      {
        "code": "charge-voltage",
        "name": "Voltage",
        "group": "Charge",
        "body": {
          "unit": "volts",
          "value": 0
        },
        "meta": {
          "oemUpdatedAt": 1731926100000,
          "fetchedAt": 1731926102000
        }
      }
    ]
  },
  "meta": {
    "version": "4.0",
    "deliveryId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "deliveredAt": 1731926100000,
    "webhookId": "abde94ff-d57d-43b9-8d09-6020db2d977a",
    "webhookName": "Battery Monitoring",
    "signalCount": 3,
    "mode": "LIVE"
  }
}

Signal Reference

The signals array contains data structured according to the Signals Schema Reference. Each signal type has a specific shape:

Charge Signals

Battery charging status and metrics

Battery Signals

State of charge and battery health

Location Signals

GPS coordinates and location data

Odometer

Distance traveled

Fuel Tank

Fuel level for ICE vehicles

All Signals

Complete signal catalog

Signal-Level Errors

Individual signals within a VEHICLE_STATE payload can contain errors if the vehicle doesn’t support that signal or if retrieval fails. When this occurs, the signal will have a status object with error details instead of a body with data:

Signal with Error

{
  "code": "location-isathome",
  "name": "IsAtHome",
  "group": "Location",
  "status": {
    "error": {
      "code": "VEHICLE_NOT_CAPABLE",
      "type": "COMPATIBILITY"
    },
    "value": "ERROR"
  }
}

Partial data delivery: When some signals succeed and others fail, you’ll receive a VEHICLE_STATE event with successful signals containing body data and failed signals containing status errors. This allows you to process available data even when some signals are unavailable.

For complete error handling, see the VEHICLE_ERROR Event documentation.

Processing VEHICLE_STATE Events

Basic Handler

function handleVehicleState(payload) {
  const { vehicleId, data } = payload;
  const { signals, triggers } = data;
  
  // Check if this is first delivery
  const isFirstDelivery = triggers.some(t => t.code === 'FIRST_DELIVERY');
  
  // Process each signal
  signals.forEach(signal => {
    if (signal.body) {
      // Signal has data
      console.log(`${signal.name}: ${JSON.stringify(signal.body)}`);
      updateDatabase(vehicleId, signal.code, signal.body);
    } else if (signal.status) {
      // Signal has error
      console.error(`${signal.name} error: ${signal.status.error.code}`);
      handleSignalError(vehicleId, signal);
    }
  });
}

Best Practices

Use eventId for deduplication

Always check if you’ve already processed an eventId before updating your database. Retries will have the same eventId but different deliveryId.

async function processWebhook(payload) {
  const { eventId } = payload;
  
  // Check if already processed
  if (await isProcessed(eventId)) {
    console.log(`Already processed ${eventId}`);
    return;
  }
  
  // Process the event
  await handleVehicleState(payload);
  
  // Mark as processed
  await markProcessed(eventId);
}

Check timestamp freshness

Use signals[].meta.oemUpdatedAt to determine if incoming data is newer than your stored state. Events can arrive out of order.

function shouldUpdate(currentData, newSignal) {
  if (!currentData) return true;
  
  return newSignal.meta.oemUpdatedAt > currentData.timestamp;
}

Handle partial failures gracefully

Some signals may succeed while others fail. Process available data and log errors for unavailable signals.

signals.forEach(signal => {
  if (signal.body) {
    updateVehicleData(signal);
  } else if (signal.status) {
    logSignalUnavailable(signal);
    // Don't block processing of other signals
  }
});

Differentiate FIRST_DELIVERY from changes

Use the triggers field to identify initial state deliveries vs. actual signal changes.

const isFirstDelivery = payload.data.triggers.some(
  t => t.code === 'FIRST_DELIVERY'
);

if (isFirstDelivery) {
  // Initialize vehicle state
  initializeVehicle(payload.data);
} else {
  // Update changed signals
  updateVehicleState(payload.data);
}

Next Steps

VEHICLE_ERROR Event

Handle error notifications

Signals Reference

Complete signal schemas and data structures

Best Practices

Implement idempotency and ordering

Delivery Behavior

Understand retry policies

Introduction

Webhooks

Vehicle Authorization & Permissions

Vehicle Data

Vehicle Commands

Management API

Compatibility API

VEHICLE_STATE Event

When This Event Fires

Trigger Configuration

Identifying Which Triggers Fired

Trigger Types

Payload Structure

Example Payloads

Signal Reference

Charge Signals

Battery Signals

Location Signals

Odometer

Fuel Tank

All Signals

Signal-Level Errors

Processing VEHICLE_STATE Events

Basic Handler

Best Practices

Next Steps

VEHICLE_ERROR Event

Signals Reference

Best Practices

Delivery Behavior

Introduction

Webhooks

Vehicle Authorization & Permissions

Vehicle Data

Vehicle Commands

Management API

Compatibility API

​When This Event Fires

​Trigger Configuration

​Identifying Which Triggers Fired

​Trigger Types

​Payload Structure

​Example Payloads

​Signal Reference

Charge Signals

Battery Signals

Location Signals

Odometer

Fuel Tank

All Signals

​Signal-Level Errors

​Processing VEHICLE_STATE Events

​Basic Handler

​Best Practices

​Next Steps

VEHICLE_ERROR Event

Signals Reference

Best Practices

Delivery Behavior

When This Event Fires

Trigger Configuration

Identifying Which Triggers Fired

Trigger Types

Payload Structure

Example Payloads

Signal Reference

Signal-Level Errors

Processing VEHICLE_STATE Events

Basic Handler

Best Practices

Next Steps