To get check-engine alerts on a Chevrolet Silverado 1500, create a DIMO Vehicle Triggers webhook on a diagnostic signal the truck's device reports, then subscribe the truck to it. On this truck the DIMO LTE R1 (2007 and newer) reports the trouble code count and distance with MIL on, while the AutoPi (2011 and newer) reports the trouble code list and distance with MIL on. Which path you follow depends on the device the truck has. Details for this truck are on the Chevrolet Silverado 1500 vehicle page. For any other vehicle, see how to get check-engine light alerts.
DIMO gives developers API access to vehicle-state data: diagnostics, fault codes, battery and fuel health, odometer, and maintenance signals. Either device needs a vehicle the owner has shared with your Developer License.
Steps
- Create a Developer License in the Developer Console and get a Developer JWT. You need your Client ID, Redirect URI and API Key.
- Get the truck shared with you through DIMO Connect. Vehicle owners consent to and control sharing, so builders get data with clear provenance.
- Check which device the Silverado 1500 has, because each one reports different signals:
- The DIMO LTE R1 (2007 and newer) reports
obdStatusDTCCount(DTC Count) andobdDistanceWithMIL(Distance with MIL On). It does not reportobdDTCListon the Silverado 1500, so the codes themselves are not available on that device. - The AutoPi (2011 and newer) reports
obdDTCList(Diagnostic Trouble Codes),obdDistanceWithMIL,obdDistanceSinceDTCClearandobdWarmupsSinceDTCClear. It does not reportobdStatusDTCCounton this truck.
- The DIMO LTE R1 (2007 and newer) reports
- Call
GET /v1/webhooks/signalswith your Developer JWT to confirm the signal name your webhook should use. - Create the webhook with
POST /v1/webhooks, again with the Developer JWT. Setservicetosignals, put the signal inmetricName, and write a condition that compares the value. Usevss.obdDistanceWithMILfor a truck on either device; on a DIMO LTE R1 truck you can usevss.obdStatusDTCCountinstead. The condition below fires when the distance with MIL on is above zero. You also set acoolDownPeriod, adescription, an HTTPStargetURL, astatusand averificationToken. - Subscribe the truck with
POST /v1/webhooks/:webhookId/subscribe/:tokenDID, where:tokenDIDis the vehicle's DID, for exampledid:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345. Or subscribe every vehicle that has shared with your Developer License using thesubscribe/allendpoint. - When the condition is met, DIMO sends a
POSTrequest to yourtargetURL. The body includes theassetDID, themetricNameand the signal value. - To see which codes are set on an AutoPi-connected truck, exchange your Developer JWT for a Vehicle JWT through the Token Exchange API. Request privilege 1 (all-time, non-location data), then query
signalsLatestforobdDTCListin the Telemetry API. On a DIMO LTE R1 truck the alert is all you get: that device does not report the code list.
The two trigger signals measure different things. obdStatusDTCCount is the number of currently active diagnostic trouble codes, and obdDistanceWithMIL is the distance travelled with the malfunction indicator lamp (MIL) on.
Code
Create the webhook with your Developer JWT. Replace the placeholders with your own values.
curl -X POST "https://vehicle-triggers-api.dimo.zone/v1/webhooks" \
-H "Authorization: Bearer <DEV_JWT>" \
-H "Content-Type: application/json" \
-d '{
"service": "signals",
"metricName": "vss.obdDistanceWithMIL",
"condition": "valueNumber > 0",
"coolDownPeriod": 3600,
"description": "Fires when a subscribed vehicle reports distance travelled with the MIL on",
"displayName": "Check-engine alert",
"targetURL": "https://your-app.example.com/webhook-receiver",
"status": "enabled",
"verificationToken": "<YOUR_VERIFICATION_TOKEN>"
}'
On an AutoPi truck, read the code list with a Vehicle JWT sent as Authorization: Bearer <Vehicle JWT>. Replace 12345 with your vehicle's token ID.
query GetTroubleCodes {
signalsLatest(tokenId: 12345) {
obdDTCList {
value
timestamp
}
}
}
To set this up for your trucks, get a Developer License in the Developer Console and follow the authentication guide. Every webhook field is described in the Vehicle Triggers API reference.
FAQ
Which Silverado 1500 connection should I use for check-engine alerts?
Both work for the alert. The DIMO LTE R1 reports a DTC count and distance with MIL on, so a webhook on either signal fires when the value is above zero. The AutoPi reports distance with MIL on for the webhook and the trouble code list, which you can read after an alert fires.
Can I read the actual trouble codes?
On the AutoPi, yes: it reports Diagnostic Trouble Codes as obdDTCList. Query it with signalsLatest using a Vehicle JWT. The DIMO LTE R1 reports a DTC count but not the code list.
Do I need the owner's permission?
Yes. You can only fetch a Vehicle JWT for a vehicle that has been shared with your Developer License. The owner grants that access through DIMO Connect.
Methodology: based on the DIMO documentation for Authentication, Building Your First App, the Vehicle Triggers API and Telemetry API Vehicle Signals, plus the Chevrolet Silverado 1500 vehicle page.