Skip to main content

​
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. 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, and for information on how to verify the payload, see the Svix verify docs.

​
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.

​
Example Payloads

[
  {
    "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
    "device_type": "VEHICLE"
  },
  {
    "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
    "device_type": "BATTERY"
  }
]

​
2. 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. 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

​
Example Payloads

[
  {
    "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
    }
  },
  {
    "metricType": "ENERGY_REMAINING",
    "vehicle": {
      "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
      "vin": "WBYF2AW010FN82676"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "energyRemainingKwh": {
      "unit": "kwh",
      "value": 65.2
    }
  },
  {
    "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
      }
    }
  },
  {
    "metricType": "ODOMETER",
    "vehicle": {
      "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
      "vin": "WBYF2AW010FN82678"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "odometer": {
      "unit": "km",
      "value": 45230.5
    }
  },
  {
    "metricType": "RANGE",
    "vehicle": {
      "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
      "vin": "WBYF2AW010FN82679"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "range": {
      "unit": "km",
      "value": 320.8
    }
  },
  {
    "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"
  },
  {
    "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"
    }
  },
  {
    "metricType": "CHARGING_STATE",
    "vehicle": {
      "id": "h9v1j-51p5d-pqv5p-b4q33-h283e",
      "vin": "WBYF2AW010FN82682"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "state": "CHARGING"
  },
  {
    "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
      }
    ]
  },
  {
    "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"
      }
    ]
  }
]

​
3. command.updated

This event is triggered when a vehicle command’s status changes.

​
Schema

The complete JSON schema for this event is available here.

​
Example Payloads

[
  {
    "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
    "device_type": "VEHICLE",
    "device_id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
    "command": "START_CHARGING",
    "status": "EXECUTED",
    "failed_reason": null
  },
  {
    "id": "h9v1j-51p5d-pqv5p-b4q33-h283d",
    "device_type": "VEHICLE",
    "device_id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
    "command": "SET_TEMPERATURE",
    "status": "FAILED",
    "failed_reason": "Vehicle not connected to network"
  },
  {
    "id": "h51p5d-pqv5p-b4q33-h283d-h9v1j",
    "device_type": "VEHICLE",
    "device_id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
    "command": "UNLOCK_DOORS",
    "status": "PENDING",
    "failed_reason": null
  },
  {
    "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
    "device_type": "VEHICLE",
    "device_id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
    "command": "SET_CHARGE_LIMIT",
    "status": "EXECUTED",
    "failed_reason": null
  },
  {
    "id": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
    "device_type": "VEHICLE",
    "device_id": "hh283d-h9v1j-51p5d-pqv5p-b4q33",
    "command": "OPEN_CHARGE_PORT",
    "status": "FAILED",
    "failed_reason": "Charge port already open"
  }
]

​
4. rate_limit.updated

This event is triggered when a rate limit is updated.

​
Schema

The complete JSON schema for this event is available here.

​
Example Payloads

[
  {
    "remaining_requests": 10,
    "max_requests": 100,
    "domain": "VEHICLE",
    "window_size_seconds": 3600,
    "object_id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
    "key": "BMW_ENERGY_API_COMMANDS"
  },
  {
    "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"
  }
]