Skip to main content

Vehicle Triggers API

Commonly known as webhooks​

Vehicle Triggers is a way for DIMO to automatically send real-time data to your systems when an event occurs. Think of it like a "push notification" for servers — instead of you constantly checking the API (polling) for updates, your app now gets notified instantly when something happens.

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.

Overview

Webhooks can also be setup directly via the DIMO Developer Console, but the options below provide a programmatic way of configuring vehicle triggers and subscribing vehicles to triggers you have configured. Webhooks are currently available in public beta. If you have feedback to share, please reach out to [email protected].

Base URL

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

Endpoints

List all webhooks

Retrieves a list of all the webhooks that have been created under your Developer License.
GET/v1/webhooks
const allWebhooks = await dimo.VehicleTriggers.listWebhooks({
    developerJwt: "eyJhbGc...ILlujqw"
});

Response

[
    {
      "id": "2r8653ab-721c-4356-ac1d-f2a620b345bc",
      "service": "telemetry.signals",
      "metricName": "speed",
      "condition": "valueNumber > 95",
      "targetURL": "https://api.igottafastcar.com/webhook-receiver",
      "coolDownPeriod": 30,
      "status": "enabled",
      "description": "Fires whenever a subscribed vehicle travels over 95kph",
      "createdAt": "2025-08-12T20:06:38.285919Z",
      "updatedAt": "2025-08-12T20:06:38.285919Z",
      "failureCount": 0,
      "displayName": "Speeding check"
    },
    {
      "id": "9d5fd26c-7d21-4425-b43c-dc279bb76036",
      "service": "telemetry.signals",
      "metricName": "powertrainTractionBatteryChargingIsCharging",
      "condition": "valueNumber == 1",
      "targetURL": "https://api.igottafastcar.com/webhook-receiver",
      "coolDownPeriod": 0,
      "status": "enabled",
      "description": "Fires when a subscribed vehicle begins a charging session",
      "createdAt": "2025-08-19T13:42:23.654711Z",
      "updatedAt": "2025-08-19T13:42:23.654711Z",
      "failureCount": 0,
      "displayName": "Vehicle charging check"
    }
]

Create a webhook

Registers a new webhook with the specified configurations and conditions.

Parameters

servicestringRequired
The subsystem producing the metric. For example, telemetry.signals or telemetry.events
metricNamestringRequired
The fully qualified signal or event name to monitor. Examples: Signals: speed, powertrainTransmissionTravelledDistance, powertrainTractionBatteryChargingIsCharging, etc. Events: ExtremeBraking, HarshAcceleration, HarshBraking, HarshCornering
conditionstringRequired
The CEL expression evaluated against the metric to decide when to fire. You can use the following condition statements: >=, <=, >, <, ==. You should always include value. In the example above, we're checking when the speed (value) is greater than 55 kph. Optionally, you can also include a previousValue to perform a check to see if things have changed, i.e. value > 55 && value != previousValue
CEL Conditions
To learn more about how CEL conditions work, check out this README
coolDownPeriodintegerRequired
The minimum number of seconds between successive firings of your webhook.
descriptionstringRequired
A brief description of the webhook conditions for your own reference.
displayNamestringOptional
An optional input to easily identify your webhook. If left blank, displayName will default to the webhookId.
targetURLstringRequired
The HTTPS endpoint URL that will receive webhook callbacks.
statusstringRequired
Should be one of the following: enabled - the webhook is actively in use, disabled - the webhook exists, but is not actively in use.
verificationTokenstringRequired
A plain/text string that is the expected token that your endpoint must echo back during verification.
POST/v1/webhooks
const newWebhook = await dimo.VehicleTriggers.createWebhook({
    developerJwt: "eyJhbGc...ILlujqw",
    service: "telemetry.signals",
    metricName: "speed",
    condition: "valueNumber > 95",
    coolDownPeriod: 30,
    description: "Fires whenever a subscribed vehicle travels over 95kph",
    displayName: "Speeding check",
    targetURL: "https://api.igottafastcar.com/webhook-receiver",
    status: "enabled",
    verificationToken: "abc123",
});

Response

{
  "id": "124e4d57-8952-4ded-96c1-0g99f1fa1234",
  "message": "Webhook registered successfully"
}

Get webhook signals

Retrieves a list of signal names available for the data field.
GET/v1/webhooks/signals
const webhookSignals = await dimo.VehicleTriggers.getWebhookSignalNames({
    developerJwt: "eyJhbGc...ILlujqw"
});

Response

// Abbreviated sample response below:
    ...
    {
      "name": "powertrainTransmissionTravelledDistance",
      "description": "Odometer reading, total distance travelled during the lifetime of the transmission.",
      "unit": "km",
      "valueType": "float64",
      "permissions": [
        "privilege:GetNonLocationHistory"
      ]
    },
...

Update a webhook

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

Parameters

webhookIdstringRequired
The Webhook ID.
requestobjectRequired
The full request payload for the webhook you're updating. See: 'Create a webhook' for more details
PUT/v1/webhooks/:webhookId
const updateWebhook = await dimo.VehicleTriggers.updateWebhook({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906",
    service: "telemetry.signals",
    metricName: "speed",
    condition: "valueNumber > 99",
    coolDownPeriod: 30,
    description: "Fires whenever a subscribed vehicle travels over 99kph",
    displayName: "Speeding check",
    targetURL: "https://api.igottafastcar.com/webhook-receiver",
    status: "enabled",
    verificationToken: "abc123",
});

Response

{
  "message": "Webhook updated successfully"
}

Delete a webhook

Deletes an existing webhook that was configured under your Developer License. In order to successfully delete a webhook, you must have first unsubscribed all vehicles from the webhook. Otherwise, the deletion will fail.

Parameters

webhookIdstringRequired
The Webhook ID.
DELETE/v1/webhooks/:webhookId
const deletedWebhook = await dimo.VehicleTriggers.deleteWebhook({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906"
});

Response

{
  "message": "Webhook deleted successfully"
}

Get vehicles susbcribed to a webhook

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

Parameters

webhookIdstringRequired
The Webhook ID.
GET/v1/webhooks/:webhookId
const subscribedVehicles = await dimo.VehicleTriggers.listSubscribedVehicles({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906"
});

Response

{
  [12345, 54321]
}

Get a list of webhooks a vehicle is subscribed to

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

Parameters

tokenDIDstringRequired
The vehicles token DID.
GET/v1/webhooks/vehicles/:tokenDID
const vehicleSubscriptions = await dimo.VehicleTriggers.listVehicleSubscriptions({
    developerJwt: "eyJhbGc...ILlujqw",
    tokenDid: "did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345"
});

Response

{
  "webhookId": "1d2bef3c-4d56-7890-b12c-dc345ee67906",
  "assetDid": "did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345",
  "createdAt": "2025-08-19T13:55:13.768969Z",
  "description": "Fires when a vehicle begins charging"
}

Subscribe a vehicle to a webhook

Subscribes a vehicle tokenDID to a specified webhook.

Parameters

webhookIdstringRequired
The Webhook ID.
tokenDIDstringRequired
The vehicles token DID.
POST/v1/webhooks/:webhookId/subscribe/:tokenDID
const subVehicle = await dimo.VehicleTriggers.subscribeVehicle({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906",
    tokenDid: "did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345"
});

Response

{
  "message": "Vehicle assigned successfully"
}

Subscribe all vehicles to a webhook

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

Parameters

webhookIdstringRequired
The Webhook ID.
POST/v1/webhooks/:webhookId/subscribe/all
const subscribeAll = await dimo.VehicleTriggers.subscribeAllVehicles({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906"
});

Response

{
  "message": "Subscribed 100 assets"
}

Unsubscribe a vehicle from a webhook

Unsubscribes a vehicle tokenDID from a specified webhook.

Parameters

webhookIdstringRequired
The Webhook ID.
tokenDIDstringRequired
The vehicles token DID.
DELETE/v1/webhooks/:webhookId/unsubscribe/:tokenDID
const unsubVehicle = await dimo.VehicleTriggers.unsubscribeVehicle({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906",
    tokenDid: "did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345"
});

Response

{
  "message": "Vehicle unsubscribed successfully"
}

Unsubscribe all vehicles from a webhook

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

Parameters

webhookIdstringRequired
The Webhook ID.
DELETE/v1/webhooks/:webhookId/unsubscribe/all
const unsubAll = await dimo.VehicleTriggers.unsubscribeAllVehicles({
    developerJwt: "eyJhbGc...ILlujqw",
    webhookId: "1d2bef3c-4d56-7890-b12c-dc345ee67906"
});

Response

{
  "message": "Unsubscribed 100 vehicles"
}

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 targetURL. The response body will contain the information that you need to handle the event as required by your application.

Data

id
The Webhook ID.
source
The Webhook ID.
producer
The Webhook ID.
specVersion
The Webhook ID.
subject
The Webhook ID.
time
The Webhook ID.
type
The Webhook ID.
datacontenttype
The Webhook ID.
dataversion
The Webhook ID.
service
The Webhook ID.
metricName
The Webhook ID.
webhookId
The Webhook ID.
webhookName
The Webhook ID.
assetDID
The Webhook ID.
condition
The Webhook ID.
name
The Webhook ID.
unit
The Webhook ID.
timestamp
The Webhook ID.
valuetype
The Webhook ID.
value
The Webhook ID.

Response

{
  "id": "6be980f3-7edf-4cab-ba72-3871f61e6cdb",
  "source": "vehicle-triggers-api",
  "producer": "3dfc572a-ea31-4e8e-8685-29fb4a24d0c2",
  "specversion": "1.0",
  "subject": "did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345",
  "time": "2025-08-14T11:04:29.685302958Z",
  "type": "dimo.trigger",
  "datacontenttype": "application/json",
  "dataversion": "telemetry.signals/v1.0",
  "data": {
    "service": "telemetry.signals",
    "metricName": "speed",
    "webhookId": "3dfc572a-ea31-4e8e-8685-29fb4a24d0c2",
    "webhookName": "3dfc572a-ea31-4e8e-8685-29fb4a24d0c2",
    "assetDID": "did:erc721:137:0xbA5738a18d83D41847dfFbDC6101d37C69c9B0cF:12345",
    "condition": "value > 55",
    "signal": {
      "name": "speed",
      "unit": "km/h",
      "timestamp": "0001-01-01T00:00:00Z",
      "valueType": "float64",
      "value": 59
    }
  }
}