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

Base URLs

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

// 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

// 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

// 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

// 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

// 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

// 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

// 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

// Coming Soon

Assign All Vehicles to a Webhook

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

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

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

// 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

// 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

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

Last updated

Was this helpful?