Webhooks API Reference

Webhooks can also be setup directly via the DIMO Developer Console, but the options below provide a programmatic way of configuring vehicle events and subscribing vehicles to events you have configured.

Webhooks are currently available in public beta. If you have feedback to share, please reach out to [email protected].

Developer Notes

Webhooks that you configure are tied to a specific Developer License. If you have multiple Developer Licenses under a single account in the DIMO Developer Console, please make sure to authenticate using the Developer JWT associated with the specific license.

Base URLs

Production

https://vehicle-events-api.dimo.zone

---

Request Structure

When creating or updating a webhook, a request object is required as application/json for raw body parameters. Below is a sample request, along with details of each key value pair:

{
   "service": "Telemetry",
   "data": "powertrainTransmissionTravelledDistance",
   "trigger": "valueNumber > 10000",
   "setup": "Realtime",
   "description": "Alert when odometer exceeds 10,000 kilometers",
   "target_uri": "https://example.com/webhook",
   "status": "Active",
   "verification_token":"abc"
 }

Key	Value
service	The DIMO service that you're making the webhook event request for. At present, this will always be Telemetry.
data	The Telemetry field that the webhook will listen for events on, for a given Token ID. In the example, we're checking powertrainTransmissionTravelledDistance to get the odometer value.
trigger	The trigger that the webhook will be listening for. You can use the following condition statements: >= , <=, >, <, = You should always include valueNumber. In the example above, we're checking when the odometer (valueNumber) is greater than 10,000km. ❗IMPORTANT: Keep in mind that the data type must match what is returned via the standard Telemetry API - either an int , float, or boolean depending on the field. In this case, odometer values are always returned as a float by the Telemetry API, so this must be specified for this trigger field.
setup	Should be one of the following: Realtime - continues firing as long as the condition remains true. Hourly - fires every hour as long as the condition remains true. [Coming Soon] Daily - fires every day as long as the condition remains true.
description	A brief description of the webhook conditions for your own reference.
target_uri	The endpoint URI that will receive POST requests from your webhook upon firing.
status	Should be one of the following: Active - the webhook is actively in use Inactive - the webhook exists, but is not actively in use.
verification_token	A plain/text string that must be returned by your target_uri webhook listener when creating or updating a webhook for verification purposes.

---

Webhook Configuration

List All Webhooks

GET {baseUrl} /v1/webhooks

Retrieves a list of all the webhooks that have been created under your Developer License.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

List All Webhooks: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.list_all_webhooks(developer_jwt)

C#

// Coming Soon   

Register A New Webhook

POST {baseUrl} /v1/webhooks

Registers a new webhook with the specified configurations and conditions.

Use application/json for raw body parameters.

Request Body

Name	Type	Description
Request*	Object	The request payload for the webhook you're creating. The below sample registers a webhook for the Telemetry API that fires when a subscribed vehicle's odometer reads over 10000 km. { "service": "Telemetry", "data": "powertrainTransmissionTravelledDistance", "trigger": "valueNumber > 10000.0", "setup": "Realtime", "description": "Trigger when odometer above 10000 km", "target_uri": "https://my-target-uri.com/webhook", "status": "Active", "verification_token": "abc" }

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Register New Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.register_webhook(developer_jwt, request)

C#

// Coming Soon   

Get Webhook Signal Names

GET {baseUrl} /v1/webhooks/signals

Retrieves a list of signal names available for the data field.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Get Webhook Signal Names: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.webhook_signals(developer_jwt)

C#

// Coming Soon   

Update an Existing Webhook

PUT {baseUrl} /v1/webhooks/{webhook_id}

Updates the parameters or configurations of an existing webhook via the webhooks webhook_id.

Use application/json for raw body parameters.

Path Parameters

Name	Type	Description
webhook_id *	String	The Webhook ID

Request Body

Name	Type	Description
Request*	Object	The full request payload for the webhook you're updating. The below sample updates a webhook for the Telemetry API that fires when a subscribed vehicle's odometer reads over 15000 km. { "service": "Telemetry", "data": "powertrainTransmissionTravelledDistance", "trigger": "valueNumber > 15000.0", "setup": "Realtime", "description": "Trigger when odometer above 15000 km", "target_uri": "https://my-target-uri.com/webhook", "status": "Active", "verification_token": "abc" }

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Update an Existing Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.update_webhook(developer_jwt, webhook_id, request)

C#

// Coming Soon   

Delete A Webhook

DELETE {baseUrl} /v1/webhooks/{webhook_id}

Deletes an existing webhook that was configured under your Developer License.

Path Parameters

Name	Type	Description
webhook_id *	String	The Webhook ID

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Delete A Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.delete_webhook(developer_jwt, webhook_id)

C#

// Coming Soon   

---

Vehicle Webhook Subscriptions

List All Vehicles Subscribed to a Webhook

GET {baseUrl} /v1/webhooks/{webhookId}

Lists all of the vehicles that are subscribed to a specific webhook that you've created.

Path Parameters

Name	Type	Description
webhookId*	String	The webhook ID from the registered webhook you created.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

List All Vehicles Subscribed to a Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.list_vehicle_subscriptions_by_event(
    developer_jwt,
    webhook_id
)

C#

// Coming Soon   

List Webhook Subscriptions for a Vehicle

GET {baseUrl} /v1/webhooks/vehicles/{tokenId}

Lists all the webhooks that a provided vehicle tokenId is subscribed to.

Path Parameters

Name	Type	Description
tokenId *	String	Vehicle token ID, this is the token ID of your vehicle NFT.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

List Webhook Subscriptions for a Vehicle: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.list_vehicle_subscriptions(developer_jwt, token_id)

C#

// Coming Soon   

Assign a Single Vehicle to a Webhook

POST {baseUrl} /v1/webhooks/{webhookId}/subscribe/{tokenId}

Subscribes a vehicle tokenId to a specified webhook.

Path Parameters

Name	Type	Description
webhookId*	String	The webhook ID from the registered webhook you created.
tokenId *	String	Vehicle token ID, this is the token ID of your vehicle NFT.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Assign a Single Vehicle to a Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.subscribe_vehicle(developer_jwt, webhook_id, token_id)

C#

// Coming Soon   

Assign All Vehicles to a Webhook

POST {baseUrl} /v1/webhooks/{webhookId}/subscribe/all

Subscribes all vehicles that have previously shared permissions with your Developer License to a specific webhook.

Important: This will only assign vehicles that have previously granted permissions to your Developer License. Vehicles that grant permissions to your license after you've assigned all vehicles to a webhook will need to be subscribed to the webhook separately, either by calling this endpoint again or by subscribing new vehicles one by one via Assign A Single Vehicle.

Path Parameters

Name	Type	Description
webhookId*	String	The webhook ID from the registered webhook you created.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Assign All Vehicles to a Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.subscribe_all_vehicles(developer_jwt, webhook_id)

C#

// Coming Soon   

Remove a Single Vehicle From a Webhook

DELETE {baseUrl} /v1/webhooks/{webhookId}/unsubscribe/{tokenId}

Unsubscribes a vehicle tokenId from a specified webhook.

Path Parameters

Name	Type	Description
webhookId*	String	The webhook ID from the registered webhook you created.
tokenId *	String	Vehicle token ID, this is the token ID of your vehicle NFT.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Remove A Single Vehicle from a Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.unsubscribe_vehicle(developer_jwt, webhook_id, token_id)

C#

// Coming Soon   

Remove All Vehicles From a Webhook

DELETE {baseUrl} /v1/webhooks/{webhookId}/unsubscribe/all

Unsubscribes all previously subscribed vehicles from a webhook you've created.

Path Parameters

Name	Type	Description
webhookId*	String	The webhook ID from the registered webhook you created.

Headers

Name	Type	Description
Authorization *	String	Developer JWT from the authentication step.

Remove All Vehicles from a Webhook: Data SDK Function Calls

TypeScript

// Coming Soon

Python

dimo.vehicle_events.unsubscribe_all_vehicles(developer_jwt, webhook_id)

C#

// Coming Soon   

Event Responses

When a vehicle that you have subscribed to an event meets the criteria you've configured in your webhook trigger, it will send a POST request to your specified targetUri. The response body will contain the information that you need to handle the event as required by your application.

Sample Configuration:

{
    "service": "Telemetry",
    "data": "speed",
    "trigger": "valueNumber > 20",
    "setup": "Realtime",
    "target_uri": "<your_target_uri>",
    "status": "Active",
    "description": "Check when a subscribed vehicle goes faster than 20kph.",
    "verification_token": "test"
  } 

Sample Response:

{
  "tokenId": 17,
  "timestamp": "2025-05-07T22:50:23Z",
  "name": "speed",
  "valueNumber": 22,
  "valueString": "",
  "source": "0xF26421509Efe92861a587482100c6d728aBf1CD0",
  "producer": "did:nft:137:0x9c94C395cBcBDe662235E0A9d3bB87Ad708561BA_31700",
  "cloudEventId": "2wmskfxoQk8r4chUZCat7tSnJLN"
}

Data	Description
tokenId	The tokenId of the vehicle the response is for.
timestamp	The time in UTC format that the event occurred on.
name	The data point that the trigger was setup for.
valueNumber	The recorded numerical value at the time of the event, if relevant (i.e. speed, odometer, etc.)
valueString	The recorded string value at the time of the event, if relevant (i.e. obdDTCList)
source	The source of the recorded data: hardware devices (ie R1, Autopi) or software connection (Smartcar, Tesla).
producer	Decentralized identifier (DID) that refers to a specific aftermarket device on the network.
cloudEventId	The specific cloud event Id related to the event. Can be used for troubleshooting if necessary.