> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mile.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing Events

> Webhook payloads for route optimization events

Routing webhooks are sent when route optimization finishes or when optimized routes are dispatched to field workers. The webhook payload contains the routing result: vehicle assignments, trip details and optimization summaries.

> [!NOTE]
>
> In the payload examples on this page, the routing configuration has 2 capacity constraints: **weight** and **volume**. Your actual payload includes the capacity constraints that you set.

## Event Types

| Event | Trigger |
| - | - |
| **onRoutingFinish** | Route optimization process completes |
| **onRoutingDispatched** | Optimized routes are dispatched to field workers |

## Payload Format

Routing webhooks come in two formats: the V3 format and the V4 format. Your organization receives one of them, and the V4 format is the default. The same format also decides whether your routing schedules run on the V3 or the V4 routing. It does not change the `/api/v3` and `/api/v4` endpoints: each one keeps its own request and response format.

| Format | Payload |
| - | - |
| V3 format | Described on this page: `result.routing[]` with `vehicleId` and flat vehicle keys, `trips[].visitId` and the V3 `summary` keys. |
| V4 format (default) | The same routing result that `GET /api/v4/result/{resultId}` returns: `result.routing[]` with `vehicle`, `summary` and `trips[]`, and `trips[].visit`. The `summary` and `configuration` objects use the key names in [Summary Keys](#summary-keys). |

Your organization receives each routing webhook in one format only, either the V3 format or the V4 format, never both. If your routing webhook still sends the V3 format and you want to switch to the V4 format, contact the support team.

### Summary Keys

The V4 format renames some `summary` and `configuration` keys of the routing result. See [Summary and Configuration](https://docs.mile.app/api-reference/routing/routing-api-versions.md#summary-and-configuration) for the full list.

## On Routing Finish

The `onRoutingFinish` event is sent when route optimization finishes processing.

The tabs show the same `onRoutingFinish` payload and routing result in the V3 format and in the V4 format. Your organization receives only one of them.

```json V3 format theme={null}
{
  "result": {
    "routing": [
      {
        "vehicleId": "64ae56d327688e090c04eff4",
        "vehicleName": "BP 4877 TFV",
        "assignee": "driver@example.com",
        "totalDistance": 62024,
        "totalVisits": 3,
        "totalTrips": 1,
        "totalTravelTime": 152,
        "finishTime": "10:42:41",
        "totalWeight": 0,
        "totalVolume": 0,
        "weightPercentage": "0%",
        "volumePercentage": "0%",
        "vehicleMaxWeight": 100,
        "vehicleMinWeight": 0,
        "vehicleMaxVolume": 100,
        "vehicleMinVolume": 0,
        "speed": 25,
        "fixedCost": 0,
        "totalNodes": 5,
        "workingTime": {
          "startTime": "07:00",
          "endTime": "17:00"
        },
        "trips": [
          {
            "isHub": true,
            "visitId": "hub-640fc11832c0de76065d8922",
            "coordinate": "-6.17549,106.79073",
            "order": 0,
            "eta": "7:00:00",
            "etd": "7:41:50",
            "waitingTime": 42,
            "visitTime": 0,
            "travelTime": 0,
            "distance": 0,
            "weight": 0,
            "volume": 0
          },
          {
            "isHub": false,
            "visitId": "taskId-64ae56a8ffffa27dbb0ea0e2",
            "visitName": "Test 1000",
            "address": "Matra Jaya 2 Jl. Waru No.26 RT 7/7 Rawamangun",
            "coordinate": "-6.16390262,106.74082965",
            "order": 1,
            "eta": "8:00:00",
            "etd": "8:10:00",
            "timeWindow": {
              "startTime": "08:00",
              "endTime": "17:00"
            },
            "timeWindows": [
              {"startTime": "08:00", "endTime": "12:00"},
              {"startTime": "14:00", "endTime": "17:00"}
            ],
            "waitingTime": 0,
            "visitTime": 10,
            "travelTime": 19,
            "distance": 7571,
            "weight": 0,
            "volume": 0,
            "tags": []
          }
        ],
        "vehicleTags": ["64ae56d327688e090c04eff4"]
      }
    ],
    "dropped": [
      {
        "id": "taskId-64ae635cd7c7984fda307d92",
        "name": "Testing 123",
        "address": "jakarta",
        "coordinate": "-6.224634691640824,106.67960171349401",
        "isHub": false,
        "tags": [],
        "capacity": {
          "weight": 0,
          "volume": 0
        },
        "timeWindow": {
          "startTime": null,
          "endTime": null
        },
        "visitTime": 12,
        "code": "RE-DROP-004",
        "reason": "No vehicle has enough working time. Extend working hours or add another vehicle."
      }
    ]
  },
  "resultCode": "Route-20230801-001",
  "_id": "64b0f67e880af90e380ff8c7",
  "name": "Routing 07-14 02:17",
  "status": "done",
  "organizationId": "640fc0f0c53fdd421d7a8d32",
  "hubId": "640fc11832c0de76065d8922",
  "hubCoordinate": "-6.17549,106.79073",
  "countryCode": "IDN",
  "createdBy": "640fc0f0c53fdd421d7a8d38",
  "createdFrom": "WEB",
  "createdTime": "2023-07-14T07:17:18+00:00",
  "updatedTime": "2023-07-14T07:17:19+00:00",
  "finishTime": "2023-07-14T07:25:18+00:00",
  "user": {
    "name": "John doe"
  },
  "configuration": {
    "name": "Default",
    "multitrip": true,
    "useAllVehicle": true,
    "returnToBase": true,
    "clustering": "none",
    "autoSpeed": false,
    "defaultSpeed": 25,
    "defaultVisitTime": 12,
    "capacityConstraint": ["weight", "volume"]
  },
  "summary": {
    "totalDistance": 123822,
    "totalVisits": 5,
    "routedVisits": 4,
    "droppedVisits": 1,
    "totalVehicles": 2,
    "usedVehicles": 2,
    "unusedVehicles": 0,
    "totalTravelTime": 301,
    "totalVisitTime": 52,
    "totalWaitingTime": 42,
    "totalSpentTime": 395,
    "avgSpeed": 25,
    "minFinishTime": "9:48:19",
    "maxFinishTime": "10:42:41",
    "avgFinishTime": "10:15:30",
    "capacityConstraint": [
      {"name": "weight", "available": 200, "optimized": 0, "percentage": 0},
      {"name": "volume", "available": 200, "optimized": 0, "percentage": 0}
    ]
  }
}
```

```json V4 format theme={null}
{
  "result": {
    "routing": [
      {
        "vehicle": {
          "id": "64ae56d327688e090c04eff4",
          "name": "BP 4877 TFV",
          "assignee": "driver@example.com",
          "speed": 25,
          "fixedCost": 0,
          "tags": ["64ae56d327688e090c04eff4"],
          "workingTime": { "startTime": "07:00", "endTime": "17:00", "multiday": 0 },
          "subHubId": null,
          "isOddEven": true
        },
        "summary": {
          "totalTravelDuration": 152,
          "totalDistance": 62024,
          "totalNodes": 5,
          "totalVisits": 3,
          "capacities": [
            { "name": "weight", "min": 0, "max": 100, "used": 0, "percentage": 0 },
            { "name": "volume", "min": 0, "max": 100, "used": 0, "percentage": 0 }
          ]
        },
        "trips": [
          {
            "order": 0,
            "visit": {
              "id": "hub-640fc11832c0de76065d8922",
              "coordinate": "-6.17549,106.79073",
              "visitDuration": 0,
              "tags": [],
              "capacities": []
            },
            "eta": "07:00:00",
            "etd": "07:41:50",
            "travelDuration": 0,
            "waitingDuration": 42,
            "distance": 0,
            "distanceFromHub": 0,
            "nodeType": "hub",
            "isHub": true,
            "allowOddEven": true
          },
          {
            "order": 1,
            "visit": {
              "id": "taskId-64ae56a8ffffa27dbb0ea0e2",
              "name": "Test 1000",
              "address": "Matra Jaya 2 Jl. Waru No.26 RT 7/7 Rawamangun",
              "coordinate": "-6.16390262,106.74082965",
              "visitDuration": 10,
              "tags": [],
              "timeWindows": [
                { "startTime": "08:00", "endTime": "12:00" },
                { "startTime": "14:00", "endTime": "17:00" }
              ],
              "capacities": [{ "name": "weight", "value": 0 }, { "name": "volume", "value": 0 }]
            },
            "eta": "08:00:00",
            "etd": "08:10:00",
            "travelDuration": 19,
            "waitingDuration": 0,
            "distance": 7571,
            "distanceFromHub": 7571,
            "nodeType": "visit",
            "isHub": false,
            "allowOddEven": true
          }
        ]
      }
    ],
    "dropped": [
      {
        "visit": {
          "id": "taskId-64ae635cd7c7984fda307d92",
          "name": "Testing 123",
          "address": "jakarta",
          "coordinate": "-6.224634691640824,106.67960171349401",
          "visitDuration": 12,
          "tags": [],
          "timeWindows": [],
          "capacities": [{ "name": "weight", "value": 0 }, { "name": "volume", "value": 0 }]
        },
        "distanceFromHub": 0,
        "code": "TIME_CONSTRAINT",
        "reason": "No vehicle has enough working time. Extend working hours or add another vehicle."
      }
    ]
  },
  "resultCode": "Route-20230801-001",
  "_id": "64b0f67e880af90e380ff8c7",
  "name": "Routing 07-14 02:17",
  "status": "done",
  "organizationId": "640fc0f0c53fdd421d7a8d32",
  "hubId": "640fc11832c0de76065d8922",
  "hubCoordinate": "-6.17549,106.79073",
  "countryCode": "IDN",
  "createdBy": "640fc0f0c53fdd421d7a8d38",
  "createdFrom": "WEB",
  "createdTime": "2023-07-14T07:17:18+00:00",
  "updatedTime": "2023-07-14T07:17:19+00:00",
  "finishTime": "2023-07-14T07:25:18+00:00",
  "user": { "name": "John doe" },
  "configuration": {
    "name": "Default",
    "multitrip": true,
    "useAllVehicles": true,
    "returnToHub": true,
    "clustering": "none",
    "autoSpeed": false,
    "defaultSpeed": 25,
    "defaultVisitDuration": 12,
    "capacityConstraints": ["weight", "volume"]
  },
  "summary": {
    "totalDistance": 123822,
    "totalVisits": 5,
    "routedVisits": 4,
    "droppedVisits": 1,
    "totalVehicles": 2,
    "usedVehicles": 2,
    "unusedVehicles": 0,
    "totalTravelDuration": 301,
    "totalVisitDuration": 52,
    "totalWaitingDuration": 42,
    "totalDuration": 395,
    "avgSpeed": 25,
    "minFinishTime": "09:48:19",
    "maxFinishTime": "10:42:41",
    "avgFinishTime": "10:15:30",
    "capacities": [
      { "name": "weight", "min": 0, "max": 200, "used": 0, "percentage": 0 },
      { "name": "volume", "min": 0, "max": 200, "used": 0, "percentage": 0 }
    ]
  }
}
```

## On Routing Dispatched

The `onRoutingDispatched` event is sent when optimized routes are dispatched to field workers. Its payload has the same routing result as the `onRoutingFinish` payload, plus dispatch status fields. The `result` object has the same format as in [On Routing Finish](#on-routing-finish), in the format your organization receives.

The `onRoutingDispatched` payload below is shortened. `[...]` and `...` stand for the same fields as in the `onRoutingFinish` payload:

```json theme={null}
{
  "dispatchStatus": "done",
  "dispatchMessage": "2/2",
  "message": "",
  "result": {
    "routing": [...],
    "dropped": [...]
  },
  "resultCode": "Route-20230801-001",
  "_id": "64b0f67e880af90e380ff8c7",
  ...
}
```

### Dispatch-Specific Fields

The `onRoutingDispatched` payload adds these fields to the `onRoutingFinish` payload.

| Field | Type | Description |
| - | - | - |
| `dispatchStatus` | string | Status of the dispatch operation |
| `dispatchMessage` | string | Number of visits dispatched successfully out of the total visits, such as `"2/2"` |
| `message` | string | Error message if dispatch failed |

## Payload Fields

The tables below describe the V3 format payload. For the V4 format, see [Routing Result](https://docs.mile.app/api-reference/routing/routing-api-versions.md#routing-result) and [Summary and Configuration](https://docs.mile.app/api-reference/routing/routing-api-versions.md#summary-and-configuration).

### Root Level

The fields at the top level of the payload.

| Field | Type | Description |
| - | - | - |
| `_id` | string | Unique identifier of the routing result |
| `resultCode` | string | Alternative identifier (e.g., `Route-20230801-001`) |
| `name` | string | Name of the route optimization |
| `status` | string | Optimization status |
| `organizationId` | string | Organization ID |
| `hubId` | string | Hub ID |
| `hubCoordinate` | string | Hub coordinates (lat,lng) |
| `countryCode` | string | Country code (e.g., `IDN`) |
| `createdBy` | string | User ID who created the routing |
| `createdFrom` | string | Source: `WEB` or `API` |
| `createdTime` | string | Creation timestamp (ISO 8601) |
| `updatedTime` | string | Last update timestamp (ISO 8601) |
| `finishTime` | string | Optimization completion timestamp |

### Routing Array

Each item in `result.routing` is the optimized route of one vehicle.

| Field | Type | Description |
| - | - | - |
| `vehicleId` | string | Vehicle unique identifier |
| `vehicleName` | string | Vehicle name/plate number |
| `assignee` | string | Assigned worker email |
| `totalDistance` | number | Total distance in meters |
| `totalVisits` | number | Number of visits |
| `totalTrips` | number | Number of trips |
| `totalTravelTime` | number | Total travel time in minutes |
| `finishTime` | string | Expected finish time |
| `totalWeight` | number | Total weight used |
| `totalVolume` | number | Total volume used |
| `weightPercentage` | string | Weight capacity utilization |
| `volumePercentage` | string | Volume capacity utilization |
| `trips` | array | Ordered list of stops |

### Trip Object

Each item in `result.routing[].trips` is one stop in the route of that vehicle.

| Field | Type | Description |
| - | - | - |
| `isHub` | boolean | Whether the stop is a hub (start/end point) |
| `visitId` | string | Visit/task identifier |
| `visitName` | string | Visit name |
| `address` | string | Visit address |
| `coordinate` | string | Coordinates (lat,lng) |
| `order` | number | Stop sequence number |
| `eta` | string | Estimated time of arrival |
| `etd` | string | Estimated time of departure |
| `waitingTime` | number | Wait time in minutes |
| `visitTime` | number | Service time in minutes |
| `travelTime` | number | Travel time from the previous stop |
| `distance` | number | Distance from the previous stop |
| `timeWindow` | object | Time window of the visit, as one object |
| `timeWindows` | array | Time windows of the visit, as a list |

### Dropped Array

Each item in `result.dropped` is a visit that could not be routed.

| Field | Type | Description |
| - | - | - |
| `id` | string | Visit identifier |
| `name` | string | Visit name |
| `address` | string | Visit address |
| `coordinate` | string | Coordinates |
| `reason` | string | Why the visit was dropped |

### Summary Object

The routing result totals, for all routes together.

| Field | Type | Description |
| - | - | - |
| `totalDistance` | number | Total distance across all routes |
| `totalVisits` | number | Total visits across all routes |
| `routedVisits` | number | Successfully routed visits |
| `droppedVisits` | number | Dropped visits count |
| `totalVehicles` | number | Total vehicles available |
| `usedVehicles` | number | Vehicles used |
| `unusedVehicles` | number | Vehicles not used |
| `totalTravelTime` | number | Total travel time in minutes |
| `totalVisitTime` | number | Total service time |
| `totalWaitingTime` | number | Total waiting time |
| `minFinishTime` | string | Earliest route finish time |
| `maxFinishTime` | string | Latest route finish time |
| `avgFinishTime` | string | Average route finish time |

### Configuration Object

The routing settings used for this routing result.

| Field | Type | Description |
| - | - | - |
| `name` | string | Configuration name |
| `multitrip` | boolean | Allow multiple trips per vehicle |
| `useAllVehicle` | boolean | Use all available vehicles |
| `returnToBase` | boolean | Vehicles return to hub |
| `clustering` | string | Clustering mode, such as `none` |
| `autoSpeed` | boolean | Automatic speed calculation |
| `defaultSpeed` | number | Default vehicle speed |
| `defaultVisitTime` | number | Default visit duration |
| `capacityConstraint` | array | Active capacity constraints |

## Response

Your webhook endpoint must return an HTTP 200 status code to acknowledge receipt of the webhook. Example response body:

```json theme={null}
{
  "status": "received"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.