​
Beta

Diagnostic webhooks are available in beta throughout December 2024 - January 2025 for organizations with Enterprise plans with Smartcar.

​
Brand Support

Diagnostics provide visibility into Diagnostic Trouble Codes (DTCs) for GM vehicles and System Status information for GM and FCA vehicles.

​
Supported Events

Diagnostic Trouble Codes (DTCs), which are 5-digit codes that indicate the component and fault type. DTC webhooks will send events for each active DTC including a timestamp it became active. A webhook event will also trigger when a DTC is no longer active. System Status, where an OEM application’s “Vehicle Health” or “System Health” reports provide a list of components and their health status. System Status webhooks will send events whenever a system reports a change from Healthy to Alert and vice-versa. A list of diagnostic systems is available in our Help Center.

​
Prerequisites

For this tutorial it is recommended to have the following in place:
  • To receive webhooks you’ll need to set up a callback URI on your server.
  • To subscribe a vehicle you’ll want to have Connect integrated into your application.

​
Setting up a Diagnostic Webhook

Navigate to Webhooks from the Smartcar Dashboard, select + Add webhook and select Event-based from the Webhooks config wizard.
Name your webhook and specify a callback URI. Your callback URI is where Smartcar will send payloads from vehicles connected to your webhook. Click Next.
Select which event types you wish to receive from System Status or Diagnostic Trouble Codes and hit Add. To receive both event types, create a second webhook.
Hit Add when ready.

After adding your webhook, you’ll need to verify your callback URI. This is to ensure Smartcar is sending data to the correct place!
Please see our API reference on how to verify a webhook, or Part II on this blog post for a more in depth guide.

​
Subscribing vehicles to a webhook

Now you’ve got your webhook set up, you can subscribe vehicles to start getting data. If you haven’t done so already, please set up Connect for your application. After going through Connect and receiving your initial access_token, you’ll first want to hit the All Vehicles endpoint to fetch the Smartcar vehicle_ids of the authorized vehicles. 
curl "https://api.smartcar.com/v2.0/vehicles" \
-H "Authorization: Bearer {token}" \
-X "GET"

With your access_token and webhook_id you can hit the Subscribe endpoint for each vehicle_id to start receiving data. 
curl "https://api.smartcar.com/v2.0/vehicles/{vehicleId}/webhooks/{webhookId}" \
-H "Authorization: Bearer {token}" \
-X "POST"

​
Example Diagnostic Trouble Code Payload

Example Response
{
  "version": "3.0",
  "webhookId": "abde94ff-d57d-43b9-8d09-6020db2d977a",
  "deliveryId": "aadc13aa-c838-41ba-b5c5-0c655ec2234a",
  "deliveryTime": "2022-04-06T01:50:00.000Z",
  "mode": "live",
  "type": "EVENT_DELIVERY",
  "data": {
    "events": [
      {
        "eventId": "1713eab1-eebc-4b4e-9433-0f2a488851c2",
        "vehicleId": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
        "userId": "9a2630ca-9496-4927-b6dc-991f47e5ed14",
        "eventTime": "2022-04-06T01:48:22.845Z",
        "eventType": "DIAGNOSTIC_TROUBLE_CODES",
	"codes": [
	  {
	    "code": "P302D",
	    "timestamp": "2024-09-05T14:48:00.000Z"
	  },
	  {
	    "code": "xxxxx",
	    "timestamp": null
	  },
	  // ... 
	]
      }
    ]
  }
}

​
Response

​
eventId
string
The unique ID of the event delivered.
​
vehicleId
string
The ID for the vehicle.
​
userID
string
The ID for the user impacted by the event.
​
eventTime
timestamp | null
The date and time the event was reported.
​
eventType
string | null
Indicates the event is a DTC.
​
code
string | null
the Diagnostic Trouble Code.
​
timestamp
timestamp | null
The date and time the DTC became active. ISO 8601, millisecond precision, UTC time zone.

​
Example System Status Payload

Example Response
{
 "version": "3.0",
 "webhookId": "abde94ff-d57d-43b9-8d09-6020db2d977a",
 "deliveryId": "aadc13aa-c838-41ba-b5c5-0c655ec2234a",
 "deliveryTime": "2022-04-06T01:50:00.000Z",
 "mode": "live",
 "type": "EVENT_DELIVERY",
 "data": {
   "events": [
     {
       "eventId": "1713eab1-eebc-4b4e-9433-0f2a488851c2",
       "vehicleId": "9af13248-3b73-4c9d-9a4b-d937ce6bc8e2",
       "userId": "9a2630ca-9496-4927-b6dc-991f47e5ed14",
       "eventTime": "2022-04-06T01:48:22.845Z",
       "eventType": "DIAGNOSTIC_SYSTEM_ALERTS",
       "alerts": [
         {
           "systemId": "SYSTEM_TPMS",
           "status": "ALERT",
           "description": "Left rear tire sensor battery low"
         },
         {
           "systemId": "SYSTEM_AIRBAG",
           "status": "ALERT",
           "description": null
         }
         // ...
       ]
     }
   ]
 }
}

​
Response

​
eventId
string
The unique ID of the event delivered.
​
vehicleId
string
The ID for the vehicle.
​
userID
string
The ID for the user impacted by the event.
​
eventTime
timestamp | null
The date and time the event was reported.
​
eventType
string | null
Indicates the event is a System Alert
​
systemID
string | null
the system reporting alert or OK status. See Smartcar Systems.
​
status
string | null
Either “ALERT” or “OK”.
​
description
string | null
A plaintext, readable description when available.
​
timestamp
timestamp | null
The date and time the DTC became active. ISO 8601, millisecond precision, UTC time zone.

​
FAQs