# Webhooks & Events

Transportial uses an event-driven architecture. Events record what happens during transport execution, and integrations can react to entity changes in real-time.

## Events

Events are polymorphic records of transport activity. They are created automatically (by GPS tracking, sensor data, etc.) or manually through the API.

### Event Types

| Type | Description |
|  --- | --- |
| `ArrivalEvent` | Vehicle arrives at a location |
| `DepartureEvent` | Vehicle departs from a location |
| `GateInEvent` | Enters a facility (warehouse, port) |
| `GateOutEvent` | Exits a facility |
| `StartMovingEvent` | Vehicle begins moving |
| `StopMovingEvent` | Vehicle stops moving |
| `SensorUpdateEvent` | Temperature, humidity, or other sensor data |
| `CapacityChangeEvent` | Loading or unloading changes cargo capacity |
| `StartEngineEvent` | Engine started |
| `StopEngineEvent` | Engine stopped |
| `GeneralEvent` | Generic event |


### Creating an Event


```bash
curl -X POST https://api.otms.transportial.com/api/event \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "type": "ArrivalEvent",
    "dateTime": "2026-03-22T14:30:00Z",
    "lifeCycle": "actual"
  }'
```

### Listing Events


```bash
curl -X GET "https://api.otms.transportial.com/api/events/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Searching Events

Use POST to search with filters:


```bash
curl -X POST "https://api.otms.transportial.com/api/events/0/50" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "type": "ArrivalEvent",
    "dateTime": "2026-03-22T00:00:00Z"
  }'
```

## Event-Driven Integrations

Rather than polling for changes, Transportial's integration system processes entity changes automatically through an event-driven queue.

### How It Works


```
Entity changes (order created, status updated, etc.)
    ↓
IntegrationObject added to processing queue
    ↓
Scheduler picks up (every ~10 seconds)
    ↓
Filters applied (should this event be processed?)
    ↓
Data sources transform and route the data
    ↓
Result: SUCCESS / ERROR / RETRY
```

### Setting Up an Integration

Create an integration that reacts to transport events:


```bash
curl -X POST https://api.otms.transportial.com/api/integration \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "ERP Sync - New Orders",
    "type": "configured",
    "enabled": true,
    "description": "Sync new transport orders to our ERP system"
  }'
```

### Monitoring Integration Activity

Check integration logs to see what has been processed:


```bash
curl -X GET "https://api.otms.transportial.com/api/integration/{id}/logs/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

View the processing queue:


```bash
curl -X GET "https://api.otms.transportial.com/api/integration/{id}/objects/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Notifications

Notifications are user-facing alerts triggered by transport events. They support push notifications and email delivery.

### Creating a Notification


```bash
curl -X POST https://api.otms.transportial.com/api/notification \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "title": "Shipment delayed",
    "message": "Transport order RTD-AMS #001 has been delayed by 2 hours",
    "push": true,
    "email": true,
    "link": "/dashboard/transport-orders"
  }'
```

### Managing Notification State


```bash
# Mark a notification as read
curl -X GET "https://api.otms.transportial.com/api/notification/{id}/read" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Mark multiple as read
curl -X POST "https://api.otms.transportial.com/api/notification/read" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '["notification-uuid-1", "notification-uuid-2"]'
```

### Listing Notifications


```bash
curl -X GET "https://api.otms.transportial.com/api/notifications/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Message Automations

Message automations let you send automated messages when transport events occur — for example, emailing a customer when their shipment is delivered.

These are configured through the platform settings and can trigger on:

- Transport order status changes
- Consignment status changes
- Trip lifecycle events (start, finish, delay)
- Custom filter conditions (using TQL — Transportial Query Language)


Automations can include file attachments (CMR documents, POD photos, etc.) and are fully configurable per platform.

## Next Steps

- Set up [integrations](/guides/integrations) to connect external systems
- Learn about the [core entity hierarchy](/guides/concepts) that generates events
- Browse the full [API Reference](/apis) for all event and notification endpoints