Gareth Wilson Gareth Wilson

Guide to Terminal Webhooks: Features and Best Practices

Published


Terminal gives software companies one API for telematics and ELD data from many fleet providers. A fleet connects its provider account through Terminal, Terminal syncs vehicles, drivers, trailers and safety events, and your application reads normalised data. Webhooks tell you when that pipeline moves: a connection is completed or broken, a sync finishes or fails, a data delivery lands, or new fleet data appears.

Read on for Terminal's 32 events and their detail objects, the difference between a finished sync and a finished delivery, Svix verification, and what Terminal leaves undocumented.

What are Terminal webhooks?

Terminal sends an HTTP POST with a JSON body to endpoints registered in its dashboard, and delivers them through Svix. Terminal's webhooks guide refers to Svix's documentation for verification rather than printing header names or steps, so the details below are Svix's: svix-id, svix-timestamp and svix-signature, with whsec_ secrets.

Each event has an id (evt_...), a type and a detail object. Unlike many APIs, Terminal puts the full related entities in detail, so most events don't need a follow-up request. Terminal also suggests webhooks as the way to forward its events to tools such as Slack or Microsoft Teams, through your own middleware, since it has no built-in destinations for them.

Terminal webhook features

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headersvix-signature
BodyJSON
Event routingBody field type
Delivery platformSvix
ConfigurationTerminal dashboard
PayloadFull related entities in detail
SecretSvix whsec_; location not documented
FailuresNon-2xx responses, which may be retried
Retry schedule, timeoutNot stated
ReplayFrom the dashboard
Validation requestNone

Events and payloads

The events most integrations start with:

EventTriggered WhenCommon Use Cases
connection.createdA connection is created with a provider accountStore the connection ID
connection.completedA user successfully completes authenticationFinish your onboarding flow
connection.disconnectedCredentials are invalid and the user must re-authenticatePrompt the user to reconnect
connection.reconnectedA disconnected connection is re-authenticatedResume normal syncing
sync.completedA connection sync completes successfullyFetch new data from Terminal
sync.failedA connection sync failsAlert, inspect sync.failureReason
connection.first_sync_completedA connection's first successful sync completesMark the connection as ready
delivery.completedA data delivery (for example to S3) finishesStart ingesting delivered files
issue.reportedAn issue with a connection is reportedSurface it to the customer
vehicle.addedA vehicle appears on a connectionUpdate your fleet records
driver.modifiedA driver changesUpdate your driver records
safety_event.addedA safety event is recordedNotify safety teams

The full list in Terminal's events overview:

  • Connection: connection.created, connection.disconnected, connection.reconnected, connection.completed, connection.updated, connection.pending_deletion, connection.deleted, connection.first_sync_completed
  • Sync: sync.requested, sync.started, sync.completed, sync.failed
  • Delivery: delivery.requested, delivery.started, delivery.failed, delivery.completed
  • Issue: issue.reported, issue.resolved
  • Provider and Link: provider.availability_updated, unsupported_provider.requested, link.analytics_event_emitted
  • Fleet data: vehicle.added, vehicle.modified, vehicle.removed, driver.added, driver.modified, driver.removed, trailer.added, trailer.modified, trailer.removed, safety_event.added, safety_event.modified

Terminal's OpenAPI spec also describes vehicle.location_updated, which the overview doesn't list, so treat the list as incomplete.

What detail contains, from the OpenAPI spec (terminal.openapi.json):

Eventsdetail keys
connection.* (created, disconnected, reconnected, updated, pending_deletion, deleted)connection
connection.completedconnection, metadata
sync.*, connection.first_sync_completedconnection, sync
delivery.*destination, delivery
issue.reported, issue.resolvedconnection, issue
provider.availability_updatedprovider, availability, update
unsupported_provider.requestedprovider, contactEmail (also dotNumber, externalId, tags)
vehicle.*, driver.*, trailer.*connection, vehicle / driver / trailer
vehicle.location_updatedconnection, location
safety_event.*connection, safetyEvent
link.analytics_event_emittedvaries by Link action

provider.availability_updated isn't tied to a connection: every application subscribed to it receives it for every provider. If you deliver data to S3 or another destination, note that sync.completed doesn't mean the files have arrived; delivery.completed does.

Setting up Terminal webhooks

  1. Build an HTTPS endpoint that accepts POST, for example https://example.com/webhooks/terminal.
  2. Register the URL in the Terminal dashboard. The docs say only that endpoints are added there, without describing the screens.
  3. Select events. connection.created, connection.disconnected, sync.completed and sync.failed are a sensible start; add the fleet data events you need.
  4. Find the endpoint's signing secret and store it as TERMINAL_WEBHOOK_SECRET. Terminal doesn't document where it is shown; if it isn't next to the endpoint, ask Terminal support.

Some event types need extra configuration on Terminal's side, so contact support if one you expect isn't offered. There's no validation request: the first delivery is a real, signed event. The Hookdeck CLI lets you watch them arrive locally:

npx hookdeck-cli listen 3000 terminal-telematics --path /webhooks/terminal

With Hookdeck. Register a Terminal source's URL in the dashboard and paste the endpoint's whsec_ secret into it. Since Terminal doesn't name its headers, the source follows Svix's svix-* names and falls back to webhook-*. It answers 200 to every POST, rejects other methods, and holds back any request that fails verification, logging it as a failure.

Securing Terminal webhooks

Per Svix, the signed content is {svix-id}.{svix-timestamp}.{raw body}, the HMAC-SHA256 key is the base64-decoded secret after whsec_, and svix-signature carries space-delimited v1,<base64> values. The function below implements that without the Svix library:

const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

A handler that tracks connection health and starts ingestion at the right moment:

const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

app.post('/webhooks/terminal', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.TERMINAL_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const payload = parseJsonObject(req.body);
  if (!payload) return res.sendStatus(400); // signed, but not a JSON object
  const { id, type, detail } = payload;
  if (!id || typeof type !== 'string' || !detail || typeof detail !== 'object') return res.sendStatus(400);
  try {
    if (await seen.has(id)) return res.sendStatus(200);

    switch (type) {
      case 'connection.disconnected':
        await customers.promptReconnect(detail.connection);
        break;
      case 'sync.failed':
        if (!detail.sync) return res.sendStatus(400);
        await alerts.syncFailed(detail.connection, detail.sync.failureReason);
        break;
      case 'delivery.completed':
        await ingestion.start(detail.destination, detail.delivery);
        break;
      case 'safety_event.added':
        await safety.notify(detail.connection, detail.safetyEvent);
        break;
      default:
        break;
    }
    await seen.add(id);
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

seen, customers, alerts, ingestion and safety stand for your own code. Unhandled types still get a 200, since Terminal counts anything else as a failure.

The Svix libraries refuse timestamps more than five minutes old. Hookdeck sets no age limit and resends Terminal's original svix-timestamp on its retries and replays, so a library check behind Hookdeck would reject them. The function above leaves the age check out.

Make Terminal webhooks production-ready. Hookdeck Event Gateway absorbs bursts of fleet data events after a large sync and routes connection, delivery and safety events to the services that need them.

Terminal webhook limitations and pain points

Signing details come from Svix, not Terminal

The Problem: You can't confirm the header names, secret format or where the secret lives from Terminal's own docs.

Why It Happens: Terminal defers to Svix's documentation and doesn't describe the dashboard screens.

Workarounds:

  • Use Svix's defaults (svix-*, whsec_), and accept webhook-* too.
  • Ask Terminal support if the secret isn't visible next to the endpoint.

How Hookdeck Can Help: Hookdeck's request log shows exactly which headers Terminal sends, and the source accepts either prefix.

Bursts of fleet events

The Problem: A large sync produces many vehicle.*, driver.* and safety_event.* events at once.

Why It Happens: Each change to fleet data is its own event, with full entities in detail.

Workarounds:

  • Acknowledge quickly and process from a queue with a concurrency limit.

How Hookdeck Can Help: Set a delivery rate on the destination so your service takes events at a pace it can handle.

Sync and delivery are different milestones

The Problem: Ingestion starts before the S3 files exist.

Why It Happens: sync.completed marks the end of Terminal's sync, not of the delivery to your destination.

Workarounds:

  • Start file ingestion on delivery.completed, and handle delivery.failed.

How Hookdeck Can Help: A filter can send delivery.* events to your ingestion service only.

Undocumented retries

The Problem: You can't tell how long Terminal will retry a failed delivery.

Why It Happens: Terminal says non-2xx responses may be retried, but gives no schedule or timeout.

Workarounds:

  • Check delivery status in Terminal's dashboard after an outage and replay messages from there.

How Hookdeck Can Help: Hookdeck acknowledges Terminal immediately and retries your service on a schedule you define.

Best practices

Use the entities in detail

Terminal includes the related objects, so update your records from detail instead of calling the API for each event.

Watch connection health

connection.disconnected means the fleet must re-authenticate. Prompt them quickly, because syncs stop until they do.

Deduplicate on id

The body id identifies the event; svix-id identifies the message. Either works for skipping retries. See our idempotency guide.

Be selective with provider.availability_updated

It arrives for every provider, regardless of your connections. Subscribe only if you show provider status to users.

Conclusion

Terminal's webhooks follow fleet connections from setup through syncs and deliveries to individual vehicles, drivers and safety events. Verify with Svix's scheme, act on delivery.completed for files, keep an eye on disconnected connections, and plan for bursts after large syncs.

Hookdeck Event Gateway smooths those bursts and routes each event type to the right service. Sign up and register a Terminal source in the Terminal dashboard.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.