> ## Documentation Index
> Fetch the complete documentation index at: https://smartcar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Reference Overview

> Understanding webhook event structure and types

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:

<CardGroup cols={3}>
  <Card title="VERIFY" icon="shield-check" href="/api-reference/webhooks/events/verify">
    One-time challenge to verify your callback URL
  </Card>

  <Card title="VEHICLE_STATE" icon="car" href="/api-reference/webhooks/events/vehicle-state">
    Fired when any monitored signal changes value
  </Card>

  <Card title="VEHICLE_ERROR" icon="triangle-exclamation" href="/api-reference/webhooks/events/vehicle-error">
    Fired when signal retrieval fails or enters error state
  </Card>
</CardGroup>

***

## Event Envelope Structure

All webhook payloads follow this consistent structure:

```json Event Envelope theme={null}
{
  "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:

<ResponseField name="eventId" type="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.
</ResponseField>

<ResponseField name="eventType" type="string" required>
  The type of event: `VERIFY`, `VEHICLE_STATE`, or `VEHICLE_ERROR`.

  Use this field to route events to appropriate handlers in your application.
</ResponseField>

<ResponseField name="vehicleId" type="string">
  The Smartcar vehicle ID this event relates to.

  **Note:** Not present in `VERIFY` events, which are webhook-level (not vehicle-specific).
</ResponseField>

<ResponseField name="data" type="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.
</ResponseField>

<ResponseField name="meta" type="object" required>
  Metadata about the webhook delivery.

  <Expandable title="meta object">
    <ResponseField name="version" type="string">
      Webhook API version (e.g., `"4.0"`)
    </ResponseField>

    <ResponseField name="webhookId" type="string">
      ID of the webhook subscription that triggered this event
    </ResponseField>

    <ResponseField name="webhookName" type="string">
      Name of the webhook subscription (user-defined in Dashboard)
    </ResponseField>

    <ResponseField name="deliveryId" type="string">
      Unique identifier for this delivery attempt. Different from `eventId` - each retry gets a new `deliveryId`.
    </ResponseField>

    <ResponseField name="deliveredAt" type="integer">
      Unix timestamp (milliseconds) when Smartcar sent this webhook
    </ResponseField>

    <ResponseField name="mode" type="string">
      Environment mode: `"LIVE"`
    </ResponseField>
  </Expandable>
</ResponseField>

## Event Delivery Guarantees

All webhook events follow these delivery characteristics:

<AccordionGroup>
  <Accordion title="At-Least-Once Delivery" icon="rotate">
    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
  </Accordion>

  <Accordion title="No Ordering Guarantees" icon="arrows-up-down">
    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
  </Accordion>

  <Accordion title="Idempotent Event IDs" icon="fingerprint">
    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.
  </Accordion>

  <Accordion title="Retry Policy" icon="arrows-rotate">
    Failed deliveries are retried up to 3 times with exponential backoff:

    | Attempt       | Wait Time   | Total Elapsed        |
    | ------------- | ----------- | -------------------- |
    | 1st (initial) | 0s          | 0s                   |
    | 2nd           | 25 seconds  | 25 seconds           |
    | 3rd           | 50 seconds  | 1 minute 15 seconds  |
    | 4th (final)   | 100 seconds | 2 minutes 55 seconds |

    See [Delivery Behavior](/api-reference/webhooks/delivery-behavior) for complete details.
  </Accordion>
</AccordionGroup>

***

## Event-Specific Documentation

<CardGroup cols={3}>
  <Card title="VERIFY Event" icon="shield-check" href="/api-reference/webhooks/events/verify">
    Initial endpoint verification challenge
  </Card>

  <Card title="VEHICLE_STATE Event" icon="car" href="/api-reference/webhooks/events/vehicle-state">
    Signal data delivery when triggers fire
  </Card>

  <Card title="VEHICLE_ERROR Event" icon="triangle-exclamation" href="/api-reference/webhooks/events/vehicle-error">
    Error notifications and resolutions
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Delivery Behavior" icon="truck-fast" href="/api-reference/webhooks/delivery-behavior">
    Understand retry policies and timeouts
  </Card>

  <Card title="Receiving Webhooks" icon="code" href="/integrations/webhooks/receiving-webhooks">
    Build your webhook endpoint
  </Card>

  <Card title="Best Practices" icon="star" href="/integrations/webhooks/best-practices/reliability">
    Implement idempotency and ordering
  </Card>

  <Card title="Payload Verification" icon="shield-check" href="/integrations/webhooks/payload-verification">
    Verify webhook signatures
  </Card>
</CardGroup>