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

# Train Arrival Webhook

> Event payload sent when a train arrives at a station

## Event Overview

The **Train Arrival** webhook fires when a train arrives at a station in your network.⁠‌‌​‌​‌​​‌‌‌‌​‌​‌‌‌‌‌‌‌‌‌⁠ It delivers equipment details, the arrival station, loaded/empty status, the train number, the arrival type (`ACTUAL` or `VIRTUAL`), and the associated work order (if any).

A trip can emit two arrival events: `Depart → VIRTUAL → ACTUAL`. `VIRTUAL` places the consist on a destination virtual track while the train remains in transit. `ACTUAL` is the physical arrival. Historical events and omitted `arrival_type` values are `ACTUAL`. Consumers that assume one arrival per departure should filter on `attributes.arrival_type`.

> [!NOTE]
>
> This webhook is triggered through ARMS workflow automation. Configure it in your workflow rules to notify external
> systems when trains arrive at specific locations.

***

## Payload Schema

```json theme={null}
{
  "event_type": "TrainArrival",
  "event_timestamp": "2026-03-10T08:15:00+00:00",
  "work_order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "linked_resources": {
    "equipment": [
      {
        "resource_id": 100001,
        "car_number": "TTGX 995823"
      },
      {
        "resource_id": 100002,
        "car_number": "BNSF 726451"
      }
    ],
    "event_station": {
      "resource_id": 500,
      "grouping_type": "station"
    }
  },
  "attributes": {
    "is_loaded": true,
    "train_number": "T-4521",
    "arrival_type": "ACTUAL"
  },
  "actor": {
    "resource_type": "User",
    "resource_id": 12345,
    "display_name": "ops@customer.com"
  }
}
```

***

## Field Reference

### Top-level Fields

| Field | Type | Required | Description |
| - | - | - | - |
| `event_type` | string | Yes | Always `"TrainArrival"` for this event. |
| `event_timestamp` | string (ISO 8601) | No | When the train arrived. `null` if unavailable. |
| `work_order_id` | string | No | ID of the associated work order. `null` if the event has no work order. |
| `linked_resources` | object | Yes | Equipment and station involved in the event. |
| `attributes` | object | Yes | Event-specific attributes. |
| `actor` | object or null | Yes | Who caused the triggering event. `null` for system-initiated events. See [Shared Payload Fields -> actor](https://docs.cedarai.com/user-docs/arms/webhooks/overview.md#actor). |

### linked\_resources.equipment

An array of equipment items on the arriving train. Always an array, even for a single car.

| Field | Type | Description |
| - | - | - |
| `resource_id` | integer | Internal equipment identifier. |
| `car_number` | string or null | Railroad car number (e.g. `"TTGX 995823"`). |

### linked\_resources.event\_station

The station where the train arrived. `null` if no station is associated.

| Field | Type | Description |
| - | - | - |
| `resource_id` | integer | Internal station identifier. |
| `grouping_type` | string | Type of location (e.g. `"station"`, `"track"`). |

### attributes

| Field | Type | Description |
| - | - | - |
| `is_loaded` | boolean | `true` if the cars are loaded, `false` if empty. |
| `train_number` | string or null | Train identifier (e.g. `"T-4521"`). `null` if no train ID is set. |
| `arrival_type` | string | `"ACTUAL"` for a physical arrival, `"VIRTUAL"` for an advance placement on a virtual track. Missing values are `"ACTUAL"`. |

***

## Example HTTP Request

This is the full HTTP request your endpoint receives:

```http theme={null}
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-Webhook-Timestamp: 1709651400
X-Webhook-Signature: <base64-encoded-ed25519-signature>
X-Webhook-KeyId: cedar-webhooks-2026
X-Webhook-Id: 550e8400-e29b-41d4-a716-446655440000

{"actor":{"display_name":"ops@customer.com","resource_id":12345,"resource_type":"User"},"attributes":{"arrival_type":"ACTUAL","is_loaded":true,"train_number":"T-4521"},"event_timestamp":"2026-03-10T08:15:00+00:00","event_type":"TrainArrival","linked_resources":{"equipment":[{"car_number":"TTGX 995823","resource_id":100001},{"car_number":"BNSF 726451","resource_id":100002}],"event_station":{"grouping_type":"station","resource_id":500}},"work_order_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}
```

> [!NOTE]
>
> The JSON body is **canonically serialized** (sorted keys, no extra whitespace) so the signature can be verified
> deterministically.⁠‌‌​‌​‌​​‌‌‌‌​‌​‌‌‌‌‌‌‌‌‌⁠ See the [Webhook Overview](https://docs.cedarai.com/user-docs/arms/webhooks/overview.md#signature-verification) for verification
> instructions.

***

## Differences from Car Actually Placed

| Aspect | Car Actually Placed | Train Arrival |
| - | - | - |
| `event_type` | `"car_actually_placed"` | `"TrainArrival"` |
| `train_number` | Not included | Included in `attributes` |
| Equipment scope | Single car typically | Multiple cars on the train |
| Trigger | Car physically placed at a track | Train arrives at a station |

***

## Setting Up This Webhook

**1. Configure Workflow**

In ARMS, create or edit a workflow rule that triggers on train arrival events.

**2. Add Webhook Effect**

Add the **Train Arrival Webhook** effect to the workflow. Provide your endpoint URL.

**3. Implement Your Endpoint**

Build an HTTPS endpoint that receives the POST, verifies the signature, and processes the event.

**4. Test**

Trigger a test event and confirm your endpoint receives and verifies the payload correctly.

***

## Related

> [card] [Webhook Overview](https://docs.cedarai.com/user-docs/arms/webhooks/overview.md)
>
> Signing, verification, public key, and shared HTTP headers.

> [card] [Car Actually Placed](https://docs.cedarai.com/user-docs/arms/webhooks/car-actually-placed.md)
>
> Webhook for individual car placement events.

> [card] [Train Departure](https://docs.cedarai.com/user-docs/arms/webhooks/train-departure.md)
>
> Webhook for train departure events, including customer/serving location.

> [!NOTE]
>
> The `linked_resources.customer_location` and `linked_resources.serving_location` fields are not currently included in the Train Arrival payload, even though the underlying event carries them.⁠‌‌​‌​‌​​‌‌‌‌​‌​‌‌‌‌‌‌‌‌‌⁠ They are included in the [Train Departure](https://docs.cedarai.com/user-docs/arms/webhooks/train-departure.md) payload.


## Related topics

- [Train Departure Webhook](https://docs.cedarai.com/user-docs/arms/webhooks/train-departure.md)
- [Train Set Webhook](https://docs.cedarai.com/user-docs/arms/webhooks/train-set.md)
- [Workflow Effect Webhooks](https://docs.cedarai.com/user-docs/arms/webhooks/overview.md)
- [Trains & Jobs](https://docs.cedarai.com/user-docs/mobile/trains.md)
- [Arrive train](https://docs.cedarai.com/api-reference/workorderservice/arrive-train.md)
