Skip to main content
Link analytics events let you track the steps a user takes while connecting their telematics account through Terminal Link. Terminal emits a link.analytics_event_emitted webhook when a user performs a tracked action, such as starting Link, searching for a provider, opening a help guide, starting OAuth, or completing a connection. This is useful when you need insight into the user journey prior to connection creation. You can use these events to understand where users drop off, which providers they search for, which unsupported providers they request, and which errors they encounter while connecting.

​
Common use cases

  • Build a funnel from link_started to create_connection_completed to understand and optimize conversion rates.
  • Track provider search and selection with provider_searched, provider_selected, and unsupported_provider_selected.
  • Identify sessions encountering connection failures, including invalid credentials, insufficient permissions, and internal errors.

​
Event structure

All Link analytics events use the same webhook event type: 
{
  "id": "evt_01GV12VR4DJP70GD1ZBK0SDWFH",
  "type": "link.analytics_event_emitted",
  "timestamp": "2026-06-07T13:51:06.059Z",
  "detail": {
    "event": "provider_selected",
    "sessionId": "019cda63-4d78-77bc-8a68-0b7ce4b48d19",
    "externalId": "fleet_456",
    "language": "en",
    "tags": ["app-4567"],
    "properties": {
      "provider": "geotab"
    }
  }
}
The detail.event field identifies the specific Link event. Fields like sessionId, externalId, language, tags, and connectionId apply across events, while the properties object depends on the event type. For example, search events include the user’s query and resultCount, provider events include a provider, OAuth redirect events include a result, and failed connection events include a failure reason. See the link.analytics_event_emitted API reference for the full schema, including every supported event name and property shape.

​
Correlating events

Use sessionId to group activity from a single Link user session. A session represents one pass through the Link flow. If the same user opens Link again later or on a different device, Terminal assigns a new sessionId. Use externalId and tags to connect Link activity back to your own systems. externalId is the identifier you pass when initializing Link. tags are the connection tags passed into Link. These fields are useful for joining Link analytics events to a customer, quote, workflow, or other internal identifier. connectionId is present when Terminal knows the related connection, such as after a connection is created or when the session was started from a reconnection URL.

​
Interpreting the funnel

A typical successful flow includes events like: 
link_started
agreement_accepted
provider_searched
provider_selected
create_connection_attempted
create_connection_completed
Users do not always move linearly through Link. They may search multiple times, select the wrong provider, go back, open help guides, retry credentials, or leave before completing the flow. There is no explicit abandonment event. To model abandonment, choose a timeout that fits your workflow and look for sessions where create_connection_completed has not occurred and the latest event is older than that threshold.

​
Subscribing

Subscribe to link.analytics_event_emitted in the Terminal dashboard. One subscription covers all Link analytics events. In your webhook handler, branch on detail.event. Terminal webhooks use at-least-once delivery. Deduplicate events by the top-level id field and handle events that arrive out of order. See Webhooks for setup, request verification, retries, and replay behavior.