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

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

https://vehicle-triggers-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.signals",
  "metricName": "speed",
  "condition": "value > 55",
  "coolDownPeriod": 30,
  "description": "This webhook is used to notify when the speed of the vehicle exceeds 55 mph.",
  "displayName": "Speed Alert",
  "status": "enabled",
  "targetURL": "https://example.com/webhook",
  "verificationToken": "1234567890"
}

Key

Value

service

The subsystem producing the metric. For example, telemetry.signals or telemetry.events

metricName

The fully qualified signal or event name to monitor. Examples:

Signals : speed, powertrainTransmissionTravelledDistance, powertrainTractionBatteryChargingIsCharging ,etc.

Events : ExtremeBraking, HarshAcceleration, HarshBraking, HarshCornering

condition

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

coolDownPeriod

The minimum number of seconds between successive firings of your webhook.

displayName

An optional input to easily identify your webhook. If left blank, displayName will default to the webhookId.

description

A brief description of the webhook conditions for your own reference.

targetURL

The HTTPS endpoint URL that will receive webhook callbacks.

status

Should be one of the following: enabled - the webhook is actively in use disabled - the webhook exists, but is not actively in use.

verificationToken

A plain/text string that is the expected token that your endpoint must echo back during verification.

* previousValue: if included in the condition, will be set to the last value that triggered the webhook, not the last value produced by the vehicle. If the webhook has not yet been triggered before, it is set to 0 for numeric signals and "" for string-based signals.

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

dimo.vehicle_events.list_all_webhooks(developer_jwt)

// 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 Telemetry Signals that fires when a subscribed vehicle's odometer reads over 10000 km.

{
    "service": "telemetry.signals",
    "metricName": "powertrainTransmissionTravelledDistance",
    "condition": "valueNumber > 10000",
    "coolDownPeriod": 30,
    "description": "Triggers when odometer above 10000 km",
    "displayName": "Odometer alert – service reminder."
    "targetURL": "https://my-target-uri.com/webhook",
    "status": "enabled",
    "verificationToken": "abc123"
}

Headers

Name

Type

Description

Authorization *

String

Developer JWT from the authentication step.

Register New Webhook: Data SDK Function Calls

// Coming Soon

dimo.vehicle_events.register_webhook(developer_jwt, request)

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

dimo.vehicle_events.webhook_signals(developer_jwt)

// Coming Soon

Update an Existing Webhook

PUT {baseUrl} /v1/webhooks/{webhookId}

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

Use application/json for raw body parameters.

Path Parameters

Name

Type

Description

webhookId *

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.signals",
    "metricName": "powertrainTransmissionTravelledDistance",
    "condition": "valueNumber > 15000",
    "coolDownPeriod": 30,
    "description": "Triggers when odometer above 15000 km",
    "displayName": "Odometer alert – service reminder."
    "targetURL": "https://my-target-uri.com/webhook",
    "status": "enabled",
    "verificationToken": "abc123"
}

Headers

Name

Type

Description

Authorization *

String

Developer JWT from the authentication step.

Update an Existing Webhook: Data SDK Function Calls

// Coming Soon

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

// Coming Soon

Delete A Webhook

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

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

Path Parameters

Name

Type

Description

webhookId *

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

dimo.vehicle_events.delete_webhook(developer_jwt, webhook_id)

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

dimo.vehicle_events.list_vehicle_subscriptions_by_event(
    developer_jwt,
    webhook_id
)

// Coming Soon

List Webhook Subscriptions for a Vehicle

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

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

Path Parameters

Name

Type

Description

tokenDID *

String

The vehicles token DID.

Headers

Name

Type

Description

Authorization *

String

Developer JWT from the authentication step.

List Webhook Subscriptions for a Vehicle: Data SDK Function Calls

// Coming Soon

dimo.vehicle_events.list_vehicle_subscriptions(developer_jwt, token_id)

// Coming Soon

Assign a Single Vehicle to a Webhook

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

Subscribes a vehicle tokenDID to a specified webhook.

Path Parameters

Name

Type

Description

webhookId*

String

The webhook ID from the registered webhook you created.

tokenDID *

String

The vehicles token DID.

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

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

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

// Coming Soon

dimo.vehicle_events.subscribe_all_vehicles(developer_jwt, webhook_id)

// Coming Soon

Remove a Single Vehicle From a Webhook

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

Unsubscribes a vehicle tokenDID from a specified webhook.

Path Parameters

Name

Type

Description

webhookId*

String

The webhook ID from the registered webhook you created.

tokenDID *

String

The vehicles token DID.

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

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

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

dimo.vehicle_events.unsubscribe_all_vehicles(developer_jwt, webhook_id)

// 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.signals",
  "metricName": "speed",
  "condition": "value > 55",
  "coolDownPeriod": 30,
  "description": "This webhook is used to notify when the speed of the vehicle exceeds 55 mph.",
  "displayName": "Speed Alert",
  "status": "enabled",
  "targetURL": "https://example.com/webhook",
  "verificationToken": "1234567890"
}

Sample 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
    }
  }
}

Data

Description

id

UUID of the specific payload of the webhook

source

Name of the webhooks repository

producer

UUID of the webhook

specVersion

Version of the spec, always 1.0

subject

The tokenDID of the vehicle

time

Timestamp that the cloudevent was created

type

Type of the cloudevent, always dimo.trigger when sent from a webhook

datacontenttype

Content type of the data, always application/json

dataversion

Versioning for the data field in the payload.

service

Service that sent the signal

metricName

Name of the signal/event

webhookId

UUID of the webhook

webhookName

Display Name of the webhook

assetDID

The tokenDID of the vehicle

condition

Condition that was used to trigger the webhook, escaped for json

name

Name of the signal

unit

Unit of the signal

timestamp

Timestamp of the signal was captured

valuetype

Data type of the value field, either float64 or string

value

Value of the signal

PreviousDIMO Triggers - Webhooks NextIntroduction

Last updated 2 days ago

Was this helpful?