Skip to main content
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

Smartcar webhooks deliver three types of events:

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

​
Event Envelope Structure

All webhook payloads follow this consistent structure:
Event Envelope
{
  "eventId": "52f6e0bb-1369-45da-a61c-9e67d092d6db",
  "eventType": "VEHICLE_STATE",
  "vehicleId": "bc6ea99e-57d1-4e41-b129-27e7eb58713e",
  "data": {
    // Event-specific data (varies by eventType)
  },
  "meta": {
    "version": "4.0",
    "webhookId": "5a8e5e38-1e12-4011-a36d-56f120053f9e",
    "webhookName": "Battery Monitor",
    "deliveryId": "5d569643-3a47-4cd1-a3ec-db5fc1f6f03b",
    "deliveredAt": 1761896351529
  }
}

​
Common Fields

All events include these fields:
​
eventId
string
required
Unique identifier for this event. Use this for deduplication to prevent processing the same event twice.Important: The eventId remains the same across delivery retries. Use this to implement idempotency.
​
eventType
string
required
The type of event: VERIFY, VEHICLE_STATE, or VEHICLE_ERROR.Use this field to route events to appropriate handlers in your application.
​
vehicleId
string
The Smartcar vehicle ID this event relates to.Note: Not present in VERIFY events, which are webhook-level (not vehicle-specific).
​
data
object
required
Event-specific data. The structure varies by eventType:
  • VERIFY: Contains a challenge string to hash and return
  • VEHICLE_STATE: Contains all signals configured in your webhook subscription
  • VEHICLE_ERROR: Contains error details and affected signals
See individual event type pages for complete data schemas.
​
meta
object
required
Metadata about the webhook delivery.

​
Event Delivery Guarantees

All webhook events follow these delivery characteristics:
Events may be delivered more than once due to retries. Always use the eventId field for deduplication to ensure you process each unique event exactly once.Why this happens:
  • Network failures
  • Your endpoint returning non-2xx status codes
  • Timeout before your endpoint responds
Events are not guaranteed to arrive in chronological order. Concurrent deliveries or network delays can cause later events to arrive before earlier ones.Best practice: Always use timestamps to determine data freshness:
  • meta.deliveredAt - when Smartcar sent the webhook
  • signals[].meta.oemUpdatedAt - when the vehicle manufacturer updated the signal
  • signals[].meta.fetchedAt - when Smartcar retrieved the signal
The eventId field remains constant across all retry attempts for the same event. The deliveryId changes with each retry.Implementation: Store processed eventId values for at least 7 days to handle late retries and reprocessing scenarios.
Failed deliveries are retried up to 3 times with exponential backoff:
AttemptWait TimeTotal Elapsed
1st (initial)0s0s
2nd25 seconds25 seconds
3rd50 seconds1 minute 15 seconds
4th (final)100 seconds2 minutes 55 seconds
See Delivery Behavior for complete details.

​
Event-Specific Documentation

VERIFY Event

Initial endpoint verification challenge

VEHICLE_STATE Event

Signal data delivery when triggers fire

VEHICLE_ERROR Event

Error notifications and resolutions

​
Next Steps

Delivery Behavior

Understand retry policies and timeouts

Receiving Webhooks

Build your webhook endpoint

Best Practices

Implement idempotency and ordering

Payload Verification

Verify webhook signatures