# Coach Job Webhook Event Reference

*Enable Coach Job webhook events and reference the in-game events included in their payloads.*

Coach Jobs use your existing TrackSim webhook configuration. The documentation and Portal call this a **Coach Job**; event identifiers use `bus_job`.

## Enable Coach Job webhook events

Edit an existing webhook in the TrackSim Portal and enable the events you want to receive:

- **Coach Job Completed**
- **Coach Job Cancelled**

The top-level `type` can only be `bus_job.completed` or `bus_job.cancelled`. The nested `events` array is separate and records everything that happened during the job.

For `bus_job.cancelled`, `satisfaction.final` and `rating_level` are `null`, `is_late` is `false`, `stops.completed` is lower than `stops.planned`, and unreached stages have `arrival.actual`, `arrival.delay_minutes` and `arrival.on_time` set to `null`. The last event is `bus_job.cancelled` with `meta.penalty`. On `bus_job.completed`, these fields are never `null`.

## Event Payload

```json
{
  "type": "fine",
  "real_time": "2026-11-12T18:20:49Z",
  "time": 1794507649,
  "location": { "x": -11701.87, "y": 40.0, "z": -6831.99 },
  "meta": { "offence": "red_signal", "amount": 360 }
}
```

| Property | Type | Description |
|---|---|---|
| `type` | `string` | Event type documented below. |
| `real_time` | `string` | When it happened, ISO 8601 UTC. |
| `time` | `int` | The same moment, Unix seconds. |
| `location` | `object` | World position `x`, `y`, `z` (`float`), in game units. |
| `meta` | `object` | Event-specific values; numbers and booleans keep their JSON type. |

## Event types

### Coach Job Started

**Type:** `bus_job.started`

This event is recorded when the Coach Job is accepted. Its location is the coach's position at the first stop; for quick jobs, this is where the coach first moves.

**Meta example**

```json
{ "market": "quick_job", "stages_count": 2 }
```

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `market` | `string` | `quick_job`, `company_job` or `tourist_job`. |
| `stages_count` | `int` | Number of stages (legs) in the route. |

### Coach Job Completed

**Type:** `bus_job.completed`

This event is recorded when the coach reaches the final stop and the game completes the job. It is the last event of a completed job, after the final `satisfaction_decrease` or `satisfaction_increase`. The keys are the game's own names and contain dots.

**Meta example**

```json
{ "revenue": 3090, "earned.xp": 0, "passenger.satisfaction": 0.383029, "distance.km": 29.0, "delivery.time": 270 }
```

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `revenue` | `int` | Money earned, in Euros in ETS2. |
| `earned.xp` | `int` | XP earned. |
| `passenger.satisfaction` | `float` | Final satisfaction 0–1, unrounded; `satisfaction.final` is the rounded copy. |
| `distance.km` | `float` | Distance the game counted for the job, km. |
| `delivery.time` | `int` | In-game minutes the job took. |

### Coach Job Cancelled

**Type:** `bus_job.cancelled`

This event is recorded when the player cancels the job. It is the last event of a cancelled job.

**Meta example**

```json
{ "penalty": 0 }
```

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `penalty` | `int` | Cancellation penalty in Euros. A default value of `0` is used when there is no penalty or the game does not provide one. |

### Satisfaction Decrease

**Type:** `satisfaction_decrease`

This event is recorded when the passengers' average satisfaction drops. The game does not state why; TrackSim determines the most likely reason from what happened just before and checks it against the game's satisfaction rules.

### Satisfaction Increase

**Type:** `satisfaction_increase`

This event is recorded when passenger satisfaction rises because of a reward or new passengers boarding at a stop.

Both satisfaction event types use the following metadata. Conditional keys only appear in the circumstances shown.

**Meta Properties**

| Property | Type | When | Description | Example |
|---|---|---|---|---|
| `reason` | `string` | always | Most likely reason, from the lists below. | `"offence"` |
| `change` | `float` | always | Change in percentage points, 1 decimal; negative for decreases. | `-13.6` |
| `before` | `float` | always | Satisfaction before, 0–1. | `0.6382` |
| `after` | `float` | always | Satisfaction after, 0–1. | `0.5024` |
| `at_stop` | `boolean` | always | `true` when it happened at a bus stop. | `false` |
| `expected_min` / `expected_max` | `float` | game-rule reasons | The game's range for that reason, percentage points, negative for decreases. | `-10.0` / `-20.0` |
| `fit` | `string` | game-rule reasons | How well `change` fits that range: `matches`, `close` (within 5 points) or `outside`. Near 0% or 100%, the change is capped and can be smaller than the range. | `"matches"` |
| `other_reasons` | `string` | when more than one fitted | Other possible reasons, comma separated. | `"crash"` |
| `game_time` | `int` | when known | In-game minutes. | `18253972` |
| `speed_kmh` | `float` | when known | Coach speed, km/h. | `32.1` |
| `speed_limit_kmh` | `float` | when known | Posted speed limit, km/h. | `50` |
| `source` | `string` | final stop only | `completed_event` means the change comes from the game's final score at the last stop, where the in-game display resets to 100%. | `"completed_event"` |
| `direction` | `string` | `severe_acceleration` | `braking` or `accelerating`. | `"braking"` |
| `peak_ms2` | `float` | `severe_acceleration`, `harsh_*` | Peak acceleration, m/s². | `13.32` |
| `wear_increase` | `float` | `crash` | Wear added, 0–1. | `0.04644` |
| `damage_tier` | `int` | `crash` | `1` (≥ 0.01 wear) or `2` (≥ 0.05). | `1` |
| `fines` | `int` | `offence` | Fines in the window. | `1` |
| `seconds_at_or_above_kmh` | `float` | `speeding` | Seconds at or above `trigger_kmh`. | `6.2` |
| `trigger_kmh` | `float` | `speeding` | Speed the game penalises, 130 km/h. | `130` |
| `max_speed_kmh` | `float` | `speeding` | Highest speed in the window. | `134.0` |
| `max_over_limit_kmh` | `float` | `over_speed_limit` | Most km/h over the posted limit. | `22.5` |
| `delay_minutes` | `int` | `late_arrival`, `on_time_arrival` | Arrival delay in in-game minutes; negative means early. | `20` |
| `km_without_penalty` | `float` | `no_penalty_distance` | Km driven since the last penalty or reward. | `30.4` |

**Decrease reasons**

| Reason | Meaning | Game range |
|---|---|---|
| `severe_acceleration` | Braking or accelerating over 11 m/s² (1.12 g). | −60 to −90% |
| `crash` | Damage to the coach (wear ≥ 0.01 / ≥ 0.05) or a crash above 6 km/h. | −5 to −46% |
| `offence` | Police fine. | −10 to −20% |
| `speeding` | 130 km/h or more for 5 seconds, not the posted limit. | −9 to −18% |
| `harsh_braking` / `harsh_acceleration` / `harsh_cornering` / `harsh_vertical` | Over 6 m/s² (0.61 g) on that axis. | −9 to −18% |
| `late_arrival` | Arrived more than 15 in-game minutes late. | −5 to −13% |
| `over_speed_limit` | Over the posted limit; informational, not a game rule. | — |
| `unknown` | Nothing recorded explains it. | — |

**Increase reasons**

| Reason | Meaning | Game range |
|---|---|---|
| `no_penalty_distance` | 30 km without a penalty. | +6 to +12% |
| `on_time_arrival` | Arrived on time at a stop. | +6 to +18% |
| `no_penalty_stage` | A whole stage without a penalty. | +6 to +12% |
| `passengers_changed` | Passengers left and boarded at a stop, so the average changed. | — |
| `unknown` | Nothing recorded explains it. | — |

### Fine

**Type:** `fine`

This event is recorded when a fine is issued.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `offence` | `string` | The offence committed. |
| `amount` | `int` | Fine amount in Euros. |

When `offence` is `speeding_camera`, the metadata also includes:

| Property | Type | Description |
|---|---|---|
| `speed_limit` | `int` | Speed limit in km/h. |
| `speed` | `int` | Coach speed in km/h. |

### Tollgate

**Type:** `tollgate`

This event is recorded when a tollgate is used.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `cost` | `int` | Toll cost in Euros. |

### Ferry

**Type:** `ferry`

This event is recorded when a ferry is used.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `cost` | `int` | Ferry cost in Euros. |
| `source_id` | `string` | Starting location ID. |
| `source_name` | `string` | Starting location name in its native language. |
| `target_id` | `string` | Ending location ID. |
| `target_name` | `string` | Ending location name in its native language. |

### Train

**Type:** `train`

This event is recorded when a train is used.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `cost` | `int` | Train cost in Euros. |
| `source_id` | `string` | Starting location ID. |
| `source_name` | `string` | Starting location name in its native language. |
| `target_id` | `string` | Ending location ID. |
| `target_name` | `string` | Ending location name in its native language. |

### Collision

**Type:** `collision`

This event is recorded when the driver causes a collision.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `wear_engine` | `float` | Coach engine wear. |
| `wear_chassis` | `float` | Coach chassis wear. |
| `wear_transmission` | `float` | Coach transmission wear. |
| `wear_cabin` | `float` | Coach cabin wear. |
| `wear_wheels` | `float` | Coach wheel wear. |

### Repair

**Type:** `repair`

This event is recorded when the coach is repaired. No metadata is available.

### Refuel

**Type:** `refuel`

This event is recorded when the coach is refuelled.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `amount` | `int` | Refuelling cost in Euros. |

### Teleport

**Type:** `teleport`

This event is recorded when a teleport is detected.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `from_x` | `float` | Original in-game X position. |
| `from_y` | `float` | Original in-game Y position. |
| `from_z` | `float` | Original in-game Z position. |
| `to_x` | `float` | New in-game X position. |
| `to_y` | `float` | New in-game Y position. |
| `to_z` | `float` | New in-game Z position. |

### Speeding

**Type:** `speeding`

This event is recorded when the driver is detected speeding.

**Meta Properties**

| Property | Type | Description |
|---|---|---|
| `speed_limit` | `int` | In-game speed limit in km/h. |
| `speed` | `float` | Coach speed in km/h. |
| `from_x` | `float` | Original in-game X position. |
| `from_y` | `float` | Original in-game Y position. |
| `from_z` | `float` | Original in-game Z position. |
| `to_x` | `float` | New in-game X position. |
| `to_y` | `float` | New in-game Y position. |
| `to_z` | `float` | New in-game Z position. |
