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

# Webhooks

> This document outlines the webhooks available

## Introduction

This document outlines the webhooks available for your integration, and how to use them. Webhooks are automated messages sent from our system to yours when a specific event occurs. The payload of each webhook is delivered in JSON format.

## Using Webhooks

You can subscribe to the webhook events below by going to the webhook page in our [Portal](https://portal.volteras.com/dashboard/webhooks).
We use the webhook platform svix, and the catalog on that Portal page allows you to:

* Add your endpoint for each event you want to subscribe to
* Get the secret key used to verify the payload for that event type (after you have added an endpoint, you will see the key at the bottom of the page)
* Get the complete JSON schema for the event type, including examples (see below for schemas and examples as well)
* Add rate limiting and filtering rules for the event type, and custom headers for each
* Test sending example payloads (set to the correct schema) to your endpoints
* View logs and webhook activity for each event type

For more details, see the [Svix documentation](https://docs.svix.com/receiving/using-app-portal/event-catalog), and for information on how to verify the payload, see the [Svix verify docs](https://docs.svix.com/receiving/verifying-payloads/how).

## Webhook Events

Here are the specific webhook events you can subscribe to.

## 1. `device.connected`

This event is triggered whenever a new device successfully connects to our platform. This is useful for tracking the provisioning and online status of your devices.

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#device.connected).

### Example Payloads

```json theme={null}
{
  "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "deviceType": "VEHICLE"
}
```

## 2. `device.disconnected`

This event is triggered whenever a device disconnects from our platform. This is useful for tracking when devices go offline.

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#device.disconnected).

### Example Payloads

```json theme={null}
{
  "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "deviceType": "VEHICLE"
}
```

## 3. `device.telemetry`

This event is used to send various types of data and metrics from a device. The specific data included in the payload is determined by the `metricType` field.

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#device.telemetry). The schema includes all supported metric types and their detailed field definitions.

### Supported Metric Types

* `STATE_OF_CHARGE` - Battery charge percentage
* `ENERGY_REMAINING` - Remaining energy in kWh
* `LOCATION` - Vehicle coordinates
* `ODOMETER` - Total distance traveled
* `RANGE` - Estimated remaining range
* `TIRES` - Tire pressure data
* `OEM_ALERT` - Diagnostic trouble codes
* `CHARGING_STATE` - Current charging status
* `DEPARTURE_TIMES` - Scheduled departure times
* `OTHER_CHARGING_DATA` - Additional charging metrics
* `OTHER_LOCATION_DATA` - Additional location metrics (speed, heading, elevation)

### Example Payloads

```json theme={null}
{
  "metricType": "STATE_OF_CHARGE",
  "vehicle": {
    "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
    "vin": "WBYF2AW010FN82675"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "stateOfCharge": {
    "unit": "percent",
    "value": 85.5
  }
}
```

```json theme={null}
{
  "metricType": "ENERGY_REMAINING",
  "vehicle": {
    "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
    "vin": "WBYF2AW010FN82676"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "energyRemainingKwh": {
    "unit": "kwh",
    "value": 65.2
  }
}
```

```json theme={null}
{
  "metricType": "LOCATION",
  "vehicle": {
    "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
    "vin": "WBYF2AW010FN82677"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "location": {
    "unit": "degree",
    "value": {
      "longitude": -122.4194,
      "latitude": 37.7749
    }
  }
}
```

```json theme={null}
{
  "metricType": "ODOMETER",
  "vehicle": {
    "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
    "vin": "WBYF2AW010FN82678"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "odometer": {
    "unit": "km",
    "value": 45230.5
  }
}
```

```json theme={null}
{
  "metricType": "RANGE",
  "vehicle": {
    "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
    "vin": "WBYF2AW010FN82679"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "range": {
    "unit": "km",
    "value": 320.8
  }
}
```

```json theme={null}
{
  "metricType": "TIRES",
  "vehicle": {
    "id": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
    "vin": "WBYF2AW010FN82680"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "pressure": {
    "unit": "KPA",
    "value": 240.5
  },
  "position": "FRONT_LEFT"
}
```

```json theme={null}
{
  "metricType": "OEM_ALERT",
  "vehicle": {
    "id": "h283d-h9v1j-51p5d-pqv5p-b4q34",
    "vin": "WBYF2AW010FN82681"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "oemAlert": {
    "status": "ACTIVE",
    "oemCode": "BMS_001",
    "oemMessage": "Battery management system fault detected",
    "oemMetadata": {
      "errorCode": "0x1234",
      "subsystem": "battery"
    },
    "mappedMessage": "Battery system requires service",
    "severity": "HIGH",
    "mappedCode": "BATTERY_MONITORING_FAILED",
    "affectedComponent": "BATTERY",
    "recommendedAction": "SERVICE_REQUIRED",
    "type": "FAULT"
  }
}
```

```json theme={null}
{
  "metricType": "CHARGING_STATE",
  "vehicle": {
    "id": "h9v1j-51p5d-pqv5p-b4q33-h283e",
    "vin": "WBYF2AW010FN82682"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "state": "CHARGING"
}
```

```json theme={null}
{
  "metricType": "DEPARTURE_TIMES",
  "vehicle": {
    "id": "h51p5d-pqv5p-b4q33-h283d-h9v1k",
    "vin": "WBYF2AW010FN82683"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "departureTimes": [
    {
      "hour": 8,
      "minute": 30,
      "daysOfWeek": [
        "MONDAY",
        "TUESDAY",
        "WEDNESDAY",
        "THURSDAY",
        "FRIDAY"
      ],
      "localTimeOffset": 60
    },
    {
      "hour": 17,
      "minute": 0,
      "daysOfWeek": [
        "MONDAY",
        "TUESDAY",
        "WEDNESDAY",
        "THURSDAY",
        "FRIDAY"
      ],
      "localTimeOffset": 60
    }
  ]
}
```

```json theme={null}
{
  "metricType": "OTHER_CHARGING_DATA",
  "vehicle": {
    "id": "hpqv5p-b4q33-h283d-h9v1j-51p5e",
    "vin": "WBYF2AW010FN82684"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "key": "maxStateOfCharge",
      "unit": "percent",
      "value": 90.0
    },
    {
      "key": "chargeRemainingTime",
      "unit": "minutes",
      "value": 45
    },
    {
      "key": "chargePowerLevel",
      "unit": "kw",
      "value": 11.0
    },
    {
      "key": "chargeCurrentLimit",
      "unit": "amps",
      "value": 32.0
    },
    {
      "key": "chargePortDoorOpen",
      "unit": "boolean",
      "value": false
    },
    {
      "key": "chargePortLatch",
      "value": "ENGAGED"
    }
  ]
}
```

## 4. `command.updated`

This event is triggered when a vehicle command's status changes (e.g., from PENDING to EXECUTED or FAILED).

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#command.updated).

### Example Payloads

```json theme={null}
{
  "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "deviceType": "VEHICLE",
  "deviceId": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "command": "START_CHARGING",
  "status": "EXECUTED",
  "failedReason": null
}
```

```json theme={null}
{
  "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "deviceType": "VEHICLE",
  "deviceId": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "command": "SET_TEMPERATURE",
  "status": "FAILED",
  "failedReason": "Vehicle not connected to network"
}
```

```json theme={null}
{
  "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "deviceType": "VEHICLE",
  "deviceId": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "command": "UNLOCK_DOORS",
  "status": "PENDING",
  "failedReason": null
}
```

```json theme={null}
{
  "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "deviceType": "VEHICLE",
  "deviceId": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
  "command": "SET_CHARGE_LIMIT",
  "status": "EXECUTED",
  "failedReason": null
}
```

```json theme={null}
{
  "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
  "deviceType": "VEHICLE",
  "deviceId": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
  "command": "OPEN_CHARGE_PORT",
  "status": "FAILED",
  "failedReason": "Charge port already open"
}
```

## 5. `rate_limit.updated`

This event is triggered when a rate limit is updated for an API endpoint or service.

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#rate_limit.updated).

### Example Payloads

```json theme={null}
{
  "remaining_requests": 10,
  "max_requests": 100,
  "domain": "VEHICLE",
  "window_size_seconds": 3600,
  "object_id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "key": "BMW_ENERGY_API_COMMANDS"
}
```

```json theme={null}
{
  "remaining_requests": 10,
  "max_requests": 100,
  "domain": "VEHICLE",
  "window_size_seconds": 3600,
  "object_id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "key": "BMW_ENERGY_API_STOP_COMMANDS"
}
```

## 6. `alert.updated`

This event is triggered when a custom (as opposed to one directly sent from the device manufacturer) alert's status, severity, or other properties change. Alerts can be created, resolved, muted, or have their severity updated.

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#alert.updated).

### Example Payloads

```json theme={null}
{
  "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "status": "ACTIVE",
  "alertDefinitionId": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "oemDeviceId": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "vin": "WBYF2AW010FN82675",
  "muted": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "currentSeverity": "HIGH",
  "resolutions": [
    {
      "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
      "definition": {
        "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
        "name": "Battery Service Required",
        "description": "Schedule service appointment for battery inspection"
      },
      "status": "PENDING",
      "steps": [
        {
          "id": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
          "status": "PENDING",
          "definition": {
            "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
            "description": "Contact service center",
            "order": 1
          }
        }
      ]
    }
  ],
  "definition": {
    "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
    "name": "Battery Management System Fault",
    "description": "Battery management system has detected a fault",
    "message": "Battery system requires service",
    "category": {
      "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
      "name": "Battery",
      "description": "Battery-related alerts"
    }
  },
  "metadata": {
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z"
  }
}
```

```json theme={null}
{
  "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "status": "RESOLVED",
  "alertDefinitionId": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "oemDeviceId": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "vin": "WBYF2AW010FN82676",
  "muted": false,
  "createdAt": "2024-01-15T09:00:00Z",
  "currentSeverity": "MEDIUM",
  "resolutions": [
    {
      "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
      "definition": {
        "id": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
        "name": "Tire Pressure Check",
        "description": "Check and adjust tire pressure"
      },
      "status": "COMPLETED",
      "steps": [
        {
          "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
          "status": "COMPLETED",
          "definition": {
            "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
            "description": "Check tire pressure",
            "order": 1
          }
        },
        {
          "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
          "status": "COMPLETED",
          "definition": {
            "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
            "description": "Inflate tires if needed",
            "order": 2
          }
        }
      ]
    }
  ],
  "definition": {
    "id": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
    "name": "Low Tire Pressure",
    "description": "One or more tires have low pressure",
    "message": "Tire pressure is below recommended level",
    "category": {
      "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
      "name": "Tires",
      "description": "Tire-related alerts"
    }
  },
  "metadata": {
    "createdAt": "2024-01-15T09:00:00Z",
    "updatedAt": "2024-01-15T10:20:00Z"
  }
}
```

```json theme={null}
{
  "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "status": "ACTIVE",
  "alertDefinitionId": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "oemDeviceId": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
  "vin": "WBYF2AW010FN82677",
  "muted": true,
  "createdAt": "2024-01-15T08:00:00Z",
  "currentSeverity": "LOW",
  "resolutions": [],
  "definition": {
    "id": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
    "name": "Maintenance Due",
    "description": "Vehicle maintenance is due",
    "message": "Scheduled maintenance is due",
    "category": {
      "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
      "name": "Maintenance",
      "description": "Maintenance-related alerts"
    }
  },
  "metadata": {
    "createdAt": "2024-01-15T08:00:00Z",
    "updatedAt": "2024-01-15T08:05:00Z"
  }
}
```

## 7. `journey.updated`

This event is triggered when a vehicle journey is created or updated. A journey represents a trip taken by a vehicle, including start and end locations, distance traveled, energy consumption, and other metrics.

### Schema

The complete JSON schema for this event is available [here](https://www.svix.com/event-types/eu/org_2cm3iv3nwXD4mYJnVQH3ykGftVo#journey.updated).

### Example Payloads

```json theme={null}
{
  "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "vehicleId": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "distanceTravelledKm": 25.5,
  "odometerStart": 45230.0,
  "odometerEnd": 45255.5,
  "energyUsedKwh": 5.2,
  "energyStartKwh": 65.0,
  "energyEndKwh": 59.8,
  "socUsed": 8.0,
  "socStart": 85,
  "socEnd": 77,
  "startTimestamp": "2024-01-15T10:00:00Z",
  "stopTimestamp": "2024-01-15T10:35:00Z",
  "startLatitude": 37.7749,
  "startLongitude": -122.4194,
  "stopLatitude": 37.7849,
  "stopLongitude": -122.4094,
  "vin": "WBYF2AW010FN82675"
}
```

```json theme={null}
{
  "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "vehicleId": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "distanceTravelledKm": 12.3,
  "odometerStart": 12345.0,
  "odometerEnd": 12357.3,
  "energyUsedKwh": null,
  "energyStartKwh": null,
  "energyEndKwh": null,
  "socUsed": null,
  "socStart": null,
  "socEnd": null,
  "startTimestamp": "2024-01-15T14:00:00Z",
  "stopTimestamp": "2024-01-15T14:20:00Z",
  "startLatitude": 40.7128,
  "startLongitude": -74.006,
  "stopLatitude": 40.7228,
  "stopLongitude": -74.016,
  "vin": "WBYF2AW010FN82676"
}
```

```json theme={null}
{
  "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
  "vehicleId": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "distanceTravelledKm": 45.8,
  "odometerStart": 78900.0,
  "odometerEnd": 78945.8,
  "energyUsedKwh": 8.5,
  "energyStartKwh": 50.0,
  "energyEndKwh": 41.5,
  "socUsed": 12.0,
  "socStart": 80,
  "socEnd": 68,
  "startTimestamp": "2024-01-15T16:00:00Z",
  "stopTimestamp": "2024-01-15T16:55:00Z",
  "startLatitude": 51.5074,
  "startLongitude": -0.1278,
  "stopLatitude": 51.5174,
  "stopLongitude": -0.1178,
  "vin": "WBYF2AW010FN82677"
}
```

```json theme={null}
{
  "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "vehicleId": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
  "distanceTravelledKm": null,
  "odometerStart": null,
  "odometerEnd": null,
  "energyUsedKwh": 3.2,
  "energyStartKwh": 40.0,
  "energyEndKwh": 36.8,
  "socUsed": 5.0,
  "socStart": 60,
  "socEnd": 55,
  "startTimestamp": "2024-01-15T18:00:00Z",
  "stopTimestamp": "2024-01-15T18:15:00Z",
  "startLatitude": null,
  "startLongitude": null,
  "stopLatitude": null,
  "stopLongitude": null,
  "vin": "WBYF2AW010FN82678"
}
```