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",
  "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.

​
Example Payloads

{
  "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. 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

{
  "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"
    }
  ]
}

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

​
Example Payloads

{
  "id": "h283d-h9v1j-51p5d-pqv5p-b4q33",
  "deviceType": "VEHICLE",
  "deviceId": "h9v1j-51p5d-pqv5p-b4q33-h283d",
  "command": "START_CHARGING",
  "status": "EXECUTED",
  "failedReason": 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"
}

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

{
  "id": "hpqv5p-b4q33-h283d-h9v1j-51p5d",
  "deviceType": "VEHICLE",
  "deviceId": "hb4q33-h283d-h9v1j-51p5d-pqv5p",
  "command": "SET_CHARGE_LIMIT",
  "status": "EXECUTED",
  "failedReason": 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.

​
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"
}

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

​
Example Payloads

{
  "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"
  }
}

{
  "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"
  }
}

{
  "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.

​
Example Payloads

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}