Using Webhooks

TrackSim uses webhooks to notify your applications when an event occurs on the TrackSim platform.

TrackSim currently supports the following events:

• job.delivered
• job.cancelled

Note: This webhook system doesn't support Discord Webhook URL. The system will automatically decline any webhook urls with Discord in the URL.

Configure webhooks for your application

To configure what webhooks are sent to your applications, you should head over to the settings page and add a new webhook URL, you may also select what events you would like sent to your webhook.

How do our webhooks work?

When an event occurs within our system, we will fire all information for that event to the webhooks you set up in the settings page. You can then use the information sent to update the information on your application.

Webhooks are sent via POST method to the URL you specified. Please see more information below for payload examples for each event.

Webhook signing

By default when add a new webhook, the system will provide you with a secret key. This key is used to create a signature for the payload sent over from our API.

We recommend that you validate the requests sent by the webhook to make sure that the data came from us and wasn't tamped with.

You can find the signature for the payload under a header called tracksim-signature, this signature is a hash generated by the payload. Below is an example in Python on how we generate our signatures.

import json, hmac, hashlib

data = json.dumps(request.data)
secret = "<webhook_secret>"
signature = hmac.new(secret.encode(), msg=data.encode(), digestmod=hashlib.sha256).hexdigest()

Using the following python you can verify the signature created matches:

import json, hmac, hashlib

data = json.dumps(request.data)
secret = "<webhook_secret>"
signature = hmac.new(secret.encode(), msg=data.encode(), digestmod=hashlib.sha256).hexdigest()

if signature == request.headers['tracksim-signature']:
  print("The Signature matches")

request.data is the payload of JSON received when by the POST method request.

secret is the key generated when connecting an settings page

hmac.new is the python function which generates the hash signature found in header tracksim-signature.

Webhook retry system

Our system is designed to retry sending webhooks up to 3 times if the webhook fails to send.

After each try the delay is increased before trying again:

• first attempt: 5 minute delay
• second attempt: 10 minute delay
• third and final attempt: 20 minute delay

Our the third attempt our system won't try again automatically. You can manually resend the webhook via the portal if you wish.

We will consider all HTTP status codes in the 200 range as a successful attempt. If you return any other status code, we will mark the webhook as failed and try again later.

You can see the history of all webhooks sent in your webhook log on the settings game.

Payload Structure

The following properties are returned in our payload structure:

Property	Type	Description
object	string	We only send the object event at this time
type	string	Event type posted e.g. job.delivered, job.cancelled
data	dict	The data relating to the event type above.

{
  "object": "event",
  "type": "...",
  "data": {}
}

Job Webhook Object

This is an example payload for the webhook events job.delivered and job.cancelled.

{
  "object": {
      "id": 1,
      "object": "job",
      "driver": {
        "id": 1,
        "steam_id": "76561198171686422",
        "username": "Nathan7471",
        "profile_photo_url": "https://tracksim.app/example-profile-pic.png",
        "client": {
          "version": {
            "name": "1.0.0",
            "branch_name": "stable",
            "platform": "windows"
          }
        },
        "last_active": "2023-01-27T16:13:08Z"
      },
      "start_time": "2023-01-26T22:52:07Z",
      "stop_time": "2023-01-26T23:49:49Z",
      "time_spent": 3461,
      "planned_distance": 160,
      "driven_distance": 184,
      "adblue_used": -3,
      "fuel_used": -59.91,
      "is_special": false,
      "is_late": true,
      "market": "cargo_market",
      "cargo": {
        "unique_id": "carb_water",
        "name": "Carbonated Water",
        "mass": 24961.20,
        "damage": 0.0
      },
      "game": {
        "short_name": "eut2",
        "language": "en_gb",
        "had_police_enabled": false
      },
      "multiplayer": {
        "mode": "truckersmp",
        "meta": {
          "player_id": "241", 
          "server": "Simulation 1"
        }
      },
      "source_city": {
        "unique_id": "joetsu",
        "name": "Joetsu"
      },
      "source_company": {
        "unique_id": "dans_jardin",
        "name": "Dans le Jardin"
      },
      "destination_city": {
        "unique_id": "toyonaka",
        "name": "Toyonaka"
      },
      "destination_company": {
        "unique_id": "wilnet_trans",
        "name": "Wilnet Transport"
      },
      "truck": {
        "unique_id": "vehicle.mercedes.actros",
        "name": "Actros",
        "brand": {
          "unique_id": "mercedes",
          "name": "Mercedes-Benz"
        },
        "odometer": 528,
        "initial_odometer": 345,
        "wheel_count": 4,
        "license_plate": " 54-57",
        "license_plate_country": {
          "unique_id": "osaka",
          "name": "osaka"
        },
        "current_damage": {
          "cabin": 0.01,
          "chassis": 0.01,
          "engine": 0,
          "transmission": 0,
          "wheels": 0
        },
        "total_damage": {
          "cabin": 0.05,
          "chassis": 0.07,
          "engine": 0.03,
          "transmission": 0.02,
          "wheels": 0.02
        },
        "top_speed": 25.71,
        "average_speed": 10.71
      },
      "trailers": [
        ...
      ],
      "events": [
        ...
      ]
  }
}

Properties

Property	Type	Description
id	int	TrackSim ID assigned to Job
object	string	Type of object returned
driver.id	int	TrackSim assigned driver ID
driver.steam_id	string	Steam 64 ID related to the driver
driver.username	string	Username for driver
driver.profile_photo_url	string	Profile picture for driver
driver.client.version.name	string	Tracker version name used to log job
driver.client.version.branch_name	string	Tracker version branch used to log job
driver.client.version.platform	string	Tracker version platform used to log job
driver.last_active	string	Last time the driver was active
start_time	datetime	Job Start time
stop_time	datetime	Job End Time
time_spent	int	Time spent on job in Seconds
planned_distance	int	Job planned distance in KMs
driven_distance	int	Job driven distance in KMs
adblue_used	float	Adblue used in litres
fuel_used	float	Fuel used in litres
is_special	boolean	If the job is a special Transport job
is_late	boolean	If the job was delivered late
market	string	The market the job was collected from. cargo_market e.g.
cargo.unique_id	string	Cargo game unique ID
cargo.name	string	Cargo name (Can be Null)
cargo.mass	float	Cargo mass in KG
cargo.damage	float	Cargo damage
game.short_name	string	Game used ats for American Truck Simulator & eut2 for Euro Truck Simulator 2
game.language	string	Language returned by game (Can be Null)
game.had_police_enabled	boolean	if police were enabled
multiplayer.mode	string	Job multiplayer mode type e.g. truckersmp, multiplayer is Convoy Mode (Can be Null)
multiplayer.meta.player_id	string	Player ID if in truckersmp (Can be Null)
multiplayer.meta.server	string	Player server if in truckersmp (Can be Null)
source_city.unique_id	string	Source City game unique ID
source_city.name	string	Source City name (Can be Null)
source_company.unique_id	string	Source Company game unique ID
source_company.name	string	Source Company name (Can be Null)
destination_city.unique_id	string	Destination City game unique ID
destination_city.name	string	Destination City Name (Can be Null)
destination_company.unique_id	string	Destination Company game unique ID
destination_company.name	string	Destination Company name (Can be Null)
truck.unique_id	string	Truck unique game ID
truck.name	string	Truck Name (Can be Null)
truck.brand.unique_id	string	Truck Brand unique ID
truck.brand.name	string	Truck Brand name (Can be Null)
truck.odometer	int	Truck odometer on job end in KMs
truck.initial_odometer	int	Truck odometer on job start in KMs
truck.wheel_count	int	Number of wheels on Truck
truck.license_plate	string	Truck License Plate
truck.license_plate_country.unique_id	string	Truck License Plate Country ID
truck.license_plate_country.name	string	Truck License Plate Country Name (Can be Null)
truck.current_damage.cabin	float	Truck Current Damage - Cabin
truck.current_damage.chassis	float	Truck Current Damage - Chassis
truck.current_damage.engine	float	Truck Current Damage - Engine
truck.current_damage.transmission	float	Truck Current Damage - Transmission
truck.current_damage.wheels	float	Truck Current Damage - Wheels
truck.total_damage.cabin	float	Truck Total Damage - Cabin
truck.total_damage.chassis	float	Truck Total Damage - Chassis
truck.total_damage.engine	float	Truck Total Damage - Engine
truck.total_damage.transmission	float	Truck Total Damage - Transmission
truck.total_damage.wheels	float	Truck Total Damage - Wheels
truck.top_speed	int	Truck top speed over Job
truck.average_speed	int	Truck average speed over Job
trailers	array	List of trailers on truck
events	array	List of events which happened during Job

Trailers payload

{
  "name": null,
  "body_type": "_chciernsoor",
  "chain_type": "single",
  "wheel_count": 6,
  "brand": null,
  "license_plate": "I-2604",
  "license_plate_country": {
    "unique_id": "latvia",
    "name": "Latvia"
  },
  "current_damage": {
    "cargo": 0,
    "chassis": 0,
    "wheels": 0
  },
  "total_damage": {
    "cargo": 0,
    "chassis": 0,
    "wheels": 0
  }
}

Properties

Property	Type	Description
name	string	Name of the trailer
body_type	string	Body type of trailer
chain_type	string	Chain type of trailer e.g. single, double
wheel_count	int	Wheel count of trailer
brand	dict	Trailer Brand, returns unique_id & name (Can be NULL)
license_plate	string	Trailer License Plate
license_plate_country.unique_id	string	Trailer License Plate Country Unique ID
license_plate_country.name	string	Traier License Plate Country name (Can be NULL)
current_damage.cargo	float	Trailer current damage - Cargo
current_damage.chassis	float	Trailer current damage - Chassis
current_damage.wheels	float	Trailer current damage - Wheels
total_damage.cargo	float	Trailer total damage - Cargo
total_damage.chassis	float	Trailer total damage - Chassis
total_damage.wheels	float	Trailer total damage - Wheels

Mods Payload

{
  "name": "Example Mod",
  "package": "example_mod"
}

Properties

Property	Type	Description
name	string	Name of the mod
package	string	ID of the mod

Event Payload

Payloads for events triggered in-game.

{
  "location": {
    "x": -104003.5436,
    "y": 11.0771,
    "z": 17014.155
  },
  "real_time": "2023-03-01T00:36:12Z",
  "time": 1677630973,
  "type": "job.started",
  "meta": {
    ...
  }
}

Event types

Job Started

Type: job.started This event is triggered when the job is started.

Meta Properties

Property	Type	Description
autoLoaded	boolean	If the job was automatically loaded.

Job Delivered

Type: job.delivered This event is triggered when the job is delivered.

Meta Properties

Property	Type	Description
revenue	int	Revenue given from job
earnedXP	int	XP from the Job
cargoDamage	float	Cargo Damage
distance	int	Distance travelled
timeTaken	int	Time taken to complete job
autoPark	boolean	If auto parked

Job Cancelled

Type: job.cancelled This event is triggered when the job is cancelled.

Meta Properties

Property	Type	Description
penalty	int	Penalty cost from cancelling job

Fine

Type: fine This event is triggered when the fine is issued.

Meta Properties

Property	Type	Description
offence	string	The offence committed
amount	int	The fee amount in Euros or Dollars

If the fine offence was a speeding_camera:

Property	Type	Description
speed_limit	int	speed limit in km/h
amount	int	speed in km/h

Tollgate

Type: tollgate This event is triggered when a tollgate is used.

Meta Properties

Property	Type	Description
cost	int	Cost to go through tollgate in Euros or Dollars

Ferry

Type: ferry This event is triggered when a ferry is used.

Meta Properties

Property	Type	Description
cost	int	Cost to go through tollgate in Euros or Dollars
source_id	string	starting location ID
source_name	string	Starting location name (in native language)
target_id	string	Ending Location ID
target_name	string	Ending Location Name (in native language)

Train

Type: train This event is triggered when a train is used in game.

Meta Properties

Property	Type	Description
cost	int	Cost to go through tollgate in Euros or Dollars
source_id	string	starting location ID
source_name	string	Starting location name (in native language)
target_id	string	Ending Location ID
target_name	string	Ending Location Name (in native language)

Collision

Type: collision This event is triggered when a driver causes a collision

Meta Properties

Property	Type	Description
wear_engine	int	Truck Engine Damage (%)
wear_chassis	string	Truck Chassis Damage (%)
wear_transmission	string	Truck Transmission Damage (%)
wear_cabin	string	Truck Cabin damage (%)
wear_wheels	string	Truck wheel damage (%)

Repair

Type: repair This event is triggered when truck is repaired.

Meta Properties No Metadata available

Refuel

Type: refuel This event is triggered when the truck is refueled.

Meta Properties

Property	Type	Description
amount	int	The fee amount in Euros or Dollars

Teleport

Type: teleport This event is triggered when a teleport is detected.

Meta Properties

Property	Type	Description
from_x	float	The original location in-game on the X-Axis.
from_y	float	The original location in-game on the Y-Axis.
from_z	float	The original location in-game on the Z-Axis.
to_x	float	The new location in-game on the X-Axis.
to_y	float	The new location in-game on the Y-Axis.
to_z	float	The new location in-game on the Z-Axis.

Speeding

Type: speeding This event is triggered when a driver is detected speeding.

Meta Properties

Property	Type	Description
speed_limit	int	In game limit in km/h
speed	float	In game limit in km/h
from_x	float	The original location in-game on the X-Axis.
from_y	float	The original location in-game on the Y-Axis.
from_z	float	The original location in-game on the Z-Axis.
to_x	float	The new location in-game on the X-Axis.
to_y	float	The new location in-game on the Y-Axis.
to_z	float	The new location in-game on the Z-Axis.