# Guide to Terminal Webhooks: Features and Best Practices

[Terminal](https://withterminal.com) 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](https://docs.withterminal.com/guides/webhooks) 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

| Feature | Details |
| --- | --- |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `svix-signature` |
| Body | JSON |
| Event routing | Body field `type` |
| Delivery platform | Svix |
| Configuration | Terminal dashboard |
| Payload | Full related entities in `detail` |
| Secret | Svix `whsec_`; location not documented |
| Failures | Non-`2xx` responses, which may be retried |
| Retry schedule, timeout | Not stated |
| Replay | From the dashboard |
| Validation request | None |

## Events and payloads

The events most integrations start with:

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `connection.created` | A connection is created with a provider account | Store the connection ID |
| `connection.completed` | A user successfully completes authentication | Finish your onboarding flow |
| `connection.disconnected` | Credentials are invalid and the user must re-authenticate | Prompt the user to reconnect |
| `connection.reconnected` | A disconnected connection is re-authenticated | Resume normal syncing |
| `sync.completed` | A connection sync completes successfully | Fetch new data from Terminal |
| `sync.failed` | A connection sync fails | Alert, inspect `sync.failureReason` |
| `connection.first_sync_completed` | A connection's first successful sync completes | Mark the connection as ready |
| `delivery.completed` | A data delivery (for example to S3) finishes | Start ingesting delivered files |
| `issue.reported` | An issue with a connection is reported | Surface it to the customer |
| `vehicle.added` | A vehicle appears on a connection | Update your fleet records |
| `driver.modified` | A driver changes | Update your driver records |
| `safety_event.added` | A safety event is recorded | Notify 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`):

| Events | `detail` keys |
| --- | --- |
| `connection.*` (created, disconnected, reconnected, updated, pending_deletion, deleted) | `connection` |
| `connection.completed` | `connection`, `metadata` |
| `sync.*`, `connection.first_sync_completed` | `connection`, `sync` |
| `delivery.*` | `destination`, `delivery` |
| `issue.reported`, `issue.resolved` | `connection`, `issue` |
| `provider.availability_updated` | `provider`, `availability`, `update` |
| `unsupported_provider.requested` | `provider`, `contactEmail` (also `dotNumber`, `externalId`, `tags`) |
| `vehicle.*`, `driver.*`, `trailer.*` | `connection`, `vehicle` / `driver` / `trailer` |
| `vehicle.location_updated` | `connection`, `location` |
| `safety_event.*` | `connection`, `safetyEvent` |
| `link.analytics_event_emitted` | varies 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](/docs/cli) lets you watch them arrive locally:

```bash
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:

```javascript
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:

```javascript
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](/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](/docs/destinations) 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](/docs/filters) 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](/docs/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](/webhooks/guides/implement-webhook-idempotency).

### 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](https://hookdeck.com) smooths those bursts and routes each event type to the right service. [Sign up](https://dashboard.hookdeck.com/signup) and register a Terminal source in the Terminal dashboard.