{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Webhooks & Events","description":"The operational transportation management API. Full access to planning, tracking, invoicing, and integrations — built on the OTM5 open data standard.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks--events","__idx":0},"children":["Webhooks & Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Transportial uses an event-driven architecture. Events record what happens during transport execution, and integrations can react to entity changes in real-time."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"events","__idx":1},"children":["Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events are polymorphic records of transport activity. They are created automatically (by GPS tracking, sensor data, etc.) or manually through the API."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"event-types","__idx":2},"children":["Event Types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ArrivalEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vehicle arrives at a location"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DepartureEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vehicle departs from a location"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GateInEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enters a facility (warehouse, port)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GateOutEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Exits a facility"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StartMovingEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vehicle begins moving"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StopMovingEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Vehicle stops moving"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SensorUpdateEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Temperature, humidity, or other sensor data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CapacityChangeEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Loading or unloading changes cargo capacity"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StartEngineEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Engine started"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["StopEngineEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Engine stopped"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GeneralEvent"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generic event"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"creating-an-event","__idx":3},"children":["Creating an Event"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/event \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"type\": \"ArrivalEvent\",\n    \"dateTime\": \"2026-03-22T14:30:00Z\",\n    \"lifeCycle\": \"actual\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"listing-events","__idx":4},"children":["Listing Events"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/events/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"searching-events","__idx":5},"children":["Searching Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use POST to search with filters:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://api.otms.transportial.com/api/events/0/50\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"type\": \"ArrivalEvent\",\n    \"dateTime\": \"2026-03-22T00:00:00Z\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-driven-integrations","__idx":6},"children":["Event-Driven Integrations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rather than polling for changes, Transportial's integration system processes entity changes automatically through an event-driven queue."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works","__idx":7},"children":["How It Works"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Entity changes (order created, status updated, etc.)\n    ↓\nIntegrationObject added to processing queue\n    ↓\nScheduler picks up (every ~10 seconds)\n    ↓\nFilters applied (should this event be processed?)\n    ↓\nData sources transform and route the data\n    ↓\nResult: SUCCESS / ERROR / RETRY\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"setting-up-an-integration","__idx":8},"children":["Setting Up an Integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create an integration that reacts to transport events:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/integration \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"name\": \"ERP Sync - New Orders\",\n    \"type\": \"configured\",\n    \"enabled\": true,\n    \"description\": \"Sync new transport orders to our ERP system\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"monitoring-integration-activity","__idx":9},"children":["Monitoring Integration Activity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check integration logs to see what has been processed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/integration/{id}/logs/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["View the processing queue:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/integration/{id}/objects/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"notifications","__idx":10},"children":["Notifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notifications are user-facing alerts triggered by transport events. They support push notifications and email delivery."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"creating-a-notification","__idx":11},"children":["Creating a Notification"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.otms.transportial.com/api/notification \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '{\n    \"title\": \"Shipment delayed\",\n    \"message\": \"Transport order RTD-AMS #001 has been delayed by 2 hours\",\n    \"push\": true,\n    \"email\": true,\n    \"link\": \"/dashboard/transport-orders\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"managing-notification-state","__idx":12},"children":["Managing Notification State"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Mark a notification as read\ncurl -X GET \"https://api.otms.transportial.com/api/notification/{id}/read\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n\n# Mark multiple as read\ncurl -X POST \"https://api.otms.transportial.com/api/notification/read\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\" \\\n  -d '[\"notification-uuid-1\", \"notification-uuid-2\"]'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"listing-notifications","__idx":13},"children":["Listing Notifications"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://api.otms.transportial.com/api/notifications/0/20\" \\\n  -H \"Authorization: Bearer YOUR_TOKEN\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"message-automations","__idx":14},"children":["Message Automations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Message automations let you send automated messages when transport events occur — for example, emailing a customer when their shipment is delivered."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are configured through the platform settings and can trigger on:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transport order status changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Consignment status changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Trip lifecycle events (start, finish, delay)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custom filter conditions (using TQL — Transportial Query Language)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Automations can include file attachments (CMR documents, POD photos, etc.) and are fully configurable per platform."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":15},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Set up ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/integrations"},"children":["integrations"]}," to connect external systems"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Learn about the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/concepts"},"children":["core entity hierarchy"]}," that generates events"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Browse the full ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis"},"children":["API Reference"]}," for all event and notification endpoints"]}]}]},"headings":[{"value":"Webhooks & Events","id":"webhooks--events","depth":1},{"value":"Events","id":"events","depth":2},{"value":"Event Types","id":"event-types","depth":3},{"value":"Creating an Event","id":"creating-an-event","depth":3},{"value":"Listing Events","id":"listing-events","depth":3},{"value":"Searching Events","id":"searching-events","depth":3},{"value":"Event-Driven Integrations","id":"event-driven-integrations","depth":2},{"value":"How It Works","id":"how-it-works","depth":3},{"value":"Setting Up an Integration","id":"setting-up-an-integration","depth":3},{"value":"Monitoring Integration Activity","id":"monitoring-integration-activity","depth":3},{"value":"Notifications","id":"notifications","depth":2},{"value":"Creating a Notification","id":"creating-a-notification","depth":3},{"value":"Managing Notification State","id":"managing-notification-state","depth":3},{"value":"Listing Notifications","id":"listing-notifications","depth":3},{"value":"Message Automations","id":"message-automations","depth":2},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Webhooks & Events"}},"lastModified":"2026-03-22T20:40:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/webhooks-and-events","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}