To get check-engine alerts on a Ford F-150, create a webhook with the DIMO Vehicle Triggers API on a diagnostic signal and subscribe the truck. On an F-150 (2010 and newer), the AutoPi reports the obdDTCList signal and obdDistanceWithMIL. The DIMO LTE R1 (2009 and newer) reports obdStatusDTCCount and obdDistanceWithMIL instead, without the code list.
DIMO gives developers API access to vehicle-state data: diagnostics, fault codes, battery and fuel health, odometer, and maintenance signals. Vehicle owners consent to and control sharing, so builders get data with clear provenance. See the Ford F-150 vehicle page for the full signal list. For any other vehicle, see how to get check-engine light alerts.
Steps
- Create a Developer License in the Developer Console. You need your Client ID, Redirect URI and API Key.
- Get the F-150 shared with your app. Use DIMO Connect to have the owner share the vehicle with you.
- Get a Developer JWT, either from the Developer Console or by using your API key with a server SDK. The webhook calls below use this token.
- To be pushed an alert instead of polling, create a webhook with the Vehicle Triggers API. Use the
signalsservice, setmetricNameto avss.-prefixed signal name such asvss.obdStatusDTCCount, and write a CEL condition such asvalueNumber > 0. On an AutoPi F-150 usevss.obdDistanceWithMIL; the AutoPi does not reportobdStatusDTCCounton the F-150. UseGET /v1/webhooks/signalsto confirm which signal names are available for webhooks. - Subscribe the vehicle to the webhook by the vehicle's DID, which looks like
did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345. DIMO sends a POST request to yourtargetURLwhen the condition is met. - To read signal values yourself, exchange the Developer JWT for a Vehicle JWT through the Token Exchange API. Request the "All-time, non-location data" permission (privilege 1), which covers the signals used here.
- Query the Telemetry API with the Vehicle JWT. On an F-150 with an AutoPi, request
obdDTCListandobdDistanceWithMILthroughsignalsLatest. On an F-150 with a DIMO LTE R1, requestobdStatusDTCCountandobdDistanceWithMIL. Pick fields to match the device the truck uses.
A count and a lamp distance are not the same reading: obdStatusDTCCount gives the number of currently active DTCs, while obdDistanceWithMIL gives the distance travelled with the malfunction indicator lamp (MIL) on.
Code
This request creates the webhook with your Developer JWT. It watches vss.obdDistanceWithMIL, which both F-150 devices list. Swap in your own target URL and verification token.
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 F-150 reports distance travelled with the MIL on",
"displayName": "F-150 check-engine alert",
"targetURL": "https://example.com/webhook-receiver",
"status": "enabled",
"verificationToken": "<YOUR_VERIFICATION_TOKEN>"
}'
This query reads the latest trouble code list and the distance driven with the malfunction indicator lamp (MIL) on. It targets an F-150 with an AutoPi. Send it to the Telemetry API with your Vehicle JWT in the Authorization header, as Bearer <Vehicle JWT>. Replace 12345 with your vehicle's token ID.
query GetCheckEngineSignals {
signalsLatest(tokenId: 12345) {
obdDTCList {
value
timestamp
}
obdDistanceWithMIL {
value
timestamp
}
}
}
Next step: pick up a Developer License in the Developer Console, follow the authentication guide, then check the Vehicle Triggers API reference for the webhook fields.
FAQ
Which F-150 connection reports the trouble code list?
The AutoPi reports obdDTCList. The DIMO LTE R1 reports a trouble code count (obdStatusDTCCount) rather than the list.
Which model years are supported?
The DIMO LTE R1 supports Ford F-150 model years 2009 and newer, and the AutoPi supports model years 2010 and newer.
Do I need a vehicle shared with me first?
Yes. You need a vehicle shared with you before you can fetch a Vehicle JWT. Sharing is done through DIMO Connect, and the owner controls it.
Can webhooks send me alerts automatically?
Yes. The Vehicle Triggers API sends a POST request to your HTTPS endpoint when a signal meets your CEL condition. Webhooks are in public beta.
Methodology: based on the DIMO documentation for Authentication, Building Your First App, the Vehicle Triggers API and Telemetry API Vehicle Signals, and on the Ford F-150 vehicle page.