Webhooks

Webhooks allow clients to have their data automatically sent in near real-time to a desired HTTP endpoint. From there, the data can be customized as desired by the client. This gives clients more control of their data, easier access, and near real-time updates.

Onboarding

Clients must work with Lytx Technical Support during onboarding. They must provide the following data.

Data	Description
API URL	The client's endpoint to which they desire GPS data sent.
Email	One or more email addresses to which alert messages will be sent in the event of an error with the client endpoint or with our service.
Authentication	The client must specify the authentication method and provide different data depending on the method. For detail, go to the "Authentication" section below.

Authentication

This webhook currently supports two types of client endpoint authentication: basic and token-based authentication. Clients must provide us with their endpoint and implement one of the supported types.

Basic Authentication

For basic authentication, a username and password are encoded into the HTTP Request Header.

Copy

Copied

{
  "userName": "webhookuser1",
  "password": "test123!"
}

Token-Based Authentication

We support 3 different methods of token-based authentication.

1. Bearer Token

For the Bearer Token method, we will add the client’s bearer token to the HTTP POST Request headers under Authorization.

Copy

Copied

{
  "tokenType": "bearer",
  "tokenValue": "<TOKEN>"
}

2. API Key

For the API Key method, we will add the client’s API key to the HTTP POST Request Headers under apikey.

Copy

Copied

{
  "tokenType": "apikey",
  "tokenValue": "<APIKEY>"
}

3. Custom Token

The Custom Token will be added to the payload HTTP Post Request Headers under the specific Token Name provided, along with the Token Value.

Copy

Copied

{
  "tokenType": "custom",
  "tokenName": "<TOKEN_NAME>",
  "tokenValue": "<TOKEN_VALUE>"
}

Delivery

After onboarding and authentication customization, data will begin sending to the specified endpoint provided during the onboarding process. Our method and timing of delivery is as follows:

Data	Method	Frequency	Notes
DTC	HTTP POST	Every 5 seconds or every 500 DTCs.	Each message can contain DTCs for multiple vehicles.
GPS	HTTP POST	Every 5 seconds or every 500 GPS points.	1 message per vehicle.

Retries on Unsuccessful Delivery

If the initial delivery is unsuccessful, delivery is continuously retried for up to 24 hours. During that time, an automated message will be sent every hour to the email address(es) provided during sign-up until a delivery is made successfully.

The message will inform the client that there is a problem with their endpoint. They will be instructed to reach out to Lytx Technical Support to help resolve the issue.

If issues persist after 24 hours, delivery is paused until the issue is resolved.