Event Reference - smartcar

Smartcar delivers webhook events to your configured endpoint. Each event notifies your application about changes to vehicle state, errors encountered during data retrieval, or verification challenges.

Event Types

VERIFY

One-time challenge to verify your callback URL

VEHICLE_STATE

Fired when any monitored signal changes value

VEHICLE_ERROR

Fired when signal retrieval fails or enters error state

`VERIFY`

A one-time event sent when you first create a webhook to verify that Smartcar can successfully deliver payloads to your callback URL.

When This Event Fires

The VERIFY event fires once when you:

Create a new webhook in the Smartcar Dashboard
Update the callback URL of an existing webhook
Click “Verify this webhook” in the Dashboard

Payload Structure

{
  "eventId": "52f6e0bb-1369-45da-a61c-9e67d092d6db",
  "eventType": "VERIFY",
  "data": {
    "challenge": "<random-string>"
  },
  "meta": {
    "version": "4.0",
    "webhookId": "5a8e5e38-1e12-4011-a36d-56f120053f9e",
    "webhookName": "Example Webhook",
    "deliveryId": "5d569643-3a47-4cd1-a3ec-db5fc1f6f03b",
    "deliveredAt": "2025-07-31T19:38:42.332Z"
  }
}

Required Response

Your endpoint must respond with a 200 status code and return the challenge hashed with your Application Management Token. Response Requirements:

Status code: 200
Content-Type: application/json
Body: { "challenge": "<HMAC-SHA256-hex>" }

Generating the HMAC: Create an HMAC-SHA256 hash of the challenge value using your Application Management Token as the secret key, then hex-encode the result.

import smartcar

hmac = smartcar.hash_challenge(
    application_management_token, 
    challenge
)

# Return in response body
return {"challenge": hmac}

If your endpoint fails to respond correctly, Smartcar will not activate the webhook. You can retry verification from the Dashboard at any time.

For step-by-step implementation guidance, see Callback URI Verification.

`VEHICLE_STATE`

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.

When This Event Fires

The VEHICLE_STATE event fires when Smartcar detects a signal value change for any trigger signal.

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.

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

This initial delivery typically occurs within seconds of subscription, but may be delayed if:

The vehicle is offline or not communicating with the OEM

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.

eventType

string

required

Always "VEHICLE_STATE" for this event type.

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")

model

string

Vehicle model (e.g., "Model 3")

year

integer

Vehicle model year

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")

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")

body

object

Signal-specific data structure. See Signals Reference for schemas.

Example Payloads

Signal Change Trigger
First Delivery

Delivered when a configured trigger signal changes value.

{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventType": "VEHICLE_STATE",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "vehicle": {
      "id": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020
    },
    "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",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "vehicle": {
      "id": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020
    },
    "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:

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:

{
  "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 a complete list of possible error codes and types, see the VEHICLE_ERROR section below.

`VEHICLE_ERROR`

Triggered when Smartcar encounters an error while attempting to retrieve signal data from a vehicle. This event helps you monitor data availability and handle errors gracefully.

When This Event Fires

The VEHICLE_ERROR event fires when:

Smartcar detects an error while retrieving signal data
The vehicle manufacturer’s API returns an error
The vehicle is offline or unreachable
Authentication, permission, or compatibility errors occur

Error Categories

Errors are categorized by type and include specific error codes:

Connected Services Account Errors

Issues with the user’s account with the vehicle manufacturer.

Type	Code	Description
`CONNECTED_SERVICES_ACCOUNT`	`ACCOUNT_ISSUE`	General account problem
`CONNECTED_SERVICES_ACCOUNT`	`AUTHENTICATION_FAILED`	Authentication credentials are invalid
`CONNECTED_SERVICES_ACCOUNT`	`PERMISSION`	User lacks necessary permissions
`CONNECTED_SERVICES_ACCOUNT`	`SUBSCRIPTION`	Required subscription is inactive or expired
`CONNECTED_SERVICES_ACCOUNT`	`VIRTUAL_KEY_REQUIRED`	Vehicle requires a virtual key to be configured

Vehicle State Errors

Issues with the vehicle’s connectivity or state.

Type	Code	Description
`VEHICLE_STATE`	`REMOTE_ACCESS_DISABLED`	Remote access is disabled on the vehicle
`VEHICLE_STATE`	`ASLEEP`	Vehicle is in sleep mode
`VEHICLE_STATE`	`UNREACHABLE`	Vehicle is not connected to the internet

Compatibility Errors

Issues with signal availability for the specific vehicle.

Type	Code	Description
`COMPATIBILITY`	`MAKE_NOT_COMPATIBLE`	Vehicle manufacturer doesn’t support this signal
`COMPATIBILITY`	`SMARTCAR_NOT_CAPABLE`	Smartcar cannot retrieve this signal yet
`COMPATIBILITY`	`VEHICLE_NOT_CAPABLE`	This specific vehicle doesn’t support the signal

Permission Errors

Issues with granted permissions.

Type	Code	Description
`PERMISSION`	`null`	Required permission not granted by user

Payload Structure

eventId

string

required

Unique identifier for this event. Use this for idempotency.

eventType

string

required

Always "VEHICLE_ERROR" for this event type.

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")

model

string

Vehicle model (e.g., "Model 3")

year

integer

Vehicle model year

errors

array

required

Array of error objects. Multiple errors may occur simultaneously.

type

string

Error category: CONNECTED_SERVICES_ACCOUNT, VEHICLE_STATE, COMPATIBILITY, or PERMISSION

code

string

Specific error code (see error categories above)

state

string

Error state: "ERROR" when error is active, "RESOLVED" when the issue has been fixed

description

string

Technical description of the error

suggestedUserMessage

string

User-friendly error message suitable for display to end users

docURL

string

Link to detailed error documentation

resolution

object

Suggested resolution steps

type

string

Resolution category: RETRY_LATER, CONTACT_SUPPORT, USER_ACTION_REQUIRED, etc.

signals

array

Array of signal objects that were affected by this error.

code

string

Kebab-case signal identifier

name

string

Human-readable signal name

group

string

Signal category

Example Payload

{
  "eventId": "5a537912-9ad3-424b-ba33-65a1704567e9",
  "eventType": "VEHICLE_ERROR",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "errors": [
      {
        "type": "COMPATIBILITY",
        "code": "VEHICLE_NOT_CAPABLE",
        "state": "ERROR",
        "description": "The vehicle is incapable of performing your request.",
        "suggestedUserMessage": "Your car is unable to perform this request.",
        "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#vehicle-not-capable",
        "resolution": {
          "type": "CONTACT_SUPPORT"
        },
        "signals": [
          {
            "code": "location-preciselocation",
            "name": "PreciseLocation",
            "group": "Location"
          },
          {
            "code": "tractionbattery-stateofcharge",
            "name": "StateOfCharge",
            "group": "TractionBattery"
          }
        ]
      }
    ],
    "vehicle": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020
    }
  },
  "meta": {
    "version": "4.0",
    "deliveryId": "48b25f8f-9fea-42e1-9085-81043682cbb8",
    "deliveredAt": 1761896351529,
    "webhookId": "123e4567-e89b-12d3-a456-426614174000",
    "webhookName": "Bad Webhook",
    "mode": "LIVE"
  }
}

Error Handling Best Practices

Log and Monitor

Track error patterns to identify systemic issues or vehicles requiring attention

Retry with Backoff

For transient errors (ASLEEP, UNREACHABLE), implement exponential backoff retries

User Notifications

Use suggestedUserMessage to notify vehicle owners when action is required

Graceful Degradation

Handle missing data gracefully in your application UI

Use the docURL field in error payloads to link users to detailed troubleshooting documentation.

Common Error Scenarios

Scenario	Type	Code	Recommended Action
Vehicle offline	`VEHICLE_STATE`	`UNREACHABLE`	Retry later; notify user if persistent
User revoked permissions	`CONNECTED_SERVICES_ACCOUNT`	`PERMISSION`	Prompt user to re-authenticate
Connected services subscription expired	`CONNECTED_SERVICES_ACCOUNT`	`SUBSCRIPTION`	Direct user to renew manufacturer subscription
Signal not supported	`COMPATIBILITY`	`VEHICLE_NOT_CAPABLE`	Remove signal from webhook or handle gracefully
Vehicle asleep	`VEHICLE_STATE`	`ASLEEP`	Retry later; avoid waking vehicle unnecessarily

Error Resolution

When an error condition is resolved (e.g., a vehicle comes back online or a user renews their subscription), Smartcar sends another VEHICLE_ERROR event with state set to "RESOLVED":

{
  "eventId": "8d9e0f1a-2b3c-4d5e-6f7a-8b9c0d1e2f3a",
  "eventType": "VEHICLE_ERROR",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "errors": [
      {
        "type": "VEHICLE_STATE",
        "code": "UNREACHABLE",
        "state": "RESOLVED",
        "description": "The vehicle is now reachable.",
        "signals": [
          {
            "code": "location-preciselocation",
            "name": "PreciseLocation",
            "group": "Location"
          }
        ]
      }
    ],
    "vehicle": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020
    }
  },
  "meta": {
    "version": "4.0",
    "deliveryId": "9f8e7d6c-5b4a-3c2b-1d0e-9f8e7d6c5b4a",
    "deliveredAt": 1761898351529,
    "webhookId": "123e4567-e89b-12d3-a456-426614174000",
    "webhookName": "Battery Monitoring",
    "mode": "LIVE"
  }
}

Track error state: Use the state field to differentiate between new errors ("ERROR") and resolved issues ("RESOLVED"). This allows you to implement automatic recovery workflows and user notifications.

Event Delivery Guarantees

All webhook events follow these delivery characteristics:

At-least-once delivery: Events may be delivered more than once. Use eventId for deduplication.
Ordering: Events are not guaranteed to arrive in chronological order. Use timestamps to determine sequence.
Idempotency: The eventId field remains constant across delivery retries for the same event.
Retries: Failed deliveries are retried with exponential backoff up to 3 days.

See Delivery Behavior for complete details.

Payload Schema

Complete schema reference for webhook payloads

Signals Reference

Signal-specific data structures

Delivery Behavior

Retry policies and delivery semantics

Error Reference

Detailed error code documentation

Introduction

Webhooks

Vehicle Authorization & Permissions

Vehicle Data

Vehicle Commands

Management API

Compatibility API

​Event Types

VERIFY

VEHICLE_STATE

VEHICLE_ERROR

​VERIFY

​When This Event Fires

​Payload Structure

​Required Response

​VEHICLE_STATE

​When This Event Fires

​Trigger Configuration

​Identifying Which Triggers Fired

​Trigger Types

​Payload Structure

​Example Payloads

​Signal Reference

​Signal-Level Errors

​VEHICLE_ERROR

​When This Event Fires

​Error Categories

​Payload Structure

​Example Payload

​Error Handling Best Practices

Log and Monitor

Retry with Backoff

User Notifications

Graceful Degradation

​Common Error Scenarios

​Error Resolution

​Event Delivery Guarantees

​Related Resources

Payload Schema

Signals Reference

Delivery Behavior

Error Reference

Event Types

`VERIFY`

When This Event Fires

Payload Structure

Required Response

`VEHICLE_STATE`

When This Event Fires

Trigger Configuration

Identifying Which Triggers Fired

Trigger Types

Payload Structure

Example Payloads

Signal Reference

Signal-Level Errors

`VEHICLE_ERROR`

When This Event Fires

Error Categories

Payload Structure

Example Payload

Error Handling Best Practices

Common Error Scenarios

Error Resolution

Event Delivery Guarantees

Related Resources