Skip to content
/
Webhooks & Events
Last updated

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

TypeDescription
ArrivalEventVehicle arrives at a location
DepartureEventVehicle departs from a location
GateInEventEnters a facility (warehouse, port)
GateOutEventExits a facility
StartMovingEventVehicle begins moving
StopMovingEventVehicle stops moving
SensorUpdateEventTemperature, humidity, or other sensor data
CapacityChangeEventLoading or unloading changes cargo capacity
StartEngineEventEngine started
StopEngineEventEngine stopped
GeneralEventGeneric event

Creating an Event

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

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:

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:

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:

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

View the processing queue:

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

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

# 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

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

Previous page
Next page