# Terminal Webhooks

[Terminal](https://withterminal.com) is a unified API for telematics and ELD data (connections to
fleet providers, syncs, vehicles, drivers, trailers, safety events). Its webhooks are delivered
through Svix, which implements Standard Webhooks. Every delivery is an HTTP
`POST` with a JSON body shaped `{ id, type, detail }` and three signature headers: `svix-id`,
`svix-timestamp`, and `svix-signature`. The event name is the top-level `type` (for example
`sync.completed`), `id` is the event ID (`evt_...`), and `detail` holds the related entities
(`connection`, `sync`, `vehicle`, ...).

## When to Use This Skill

* How do I receive Terminal webhooks?
* How do I verify Terminal webhook signatures (`svix-signature`)?
* How do I handle `sync.completed`, `sync.failed`, or `connection.disconnected` events?
* How do I react to `vehicle.added`, `driver.modified`, or `safety_event.added`?
* Why is my Terminal webhook signature verification failing, or rejecting Hookdeck retries?

## Verification (core)

Signed content is `{svix-id}.{svix-timestamp}.{raw body}`. Svix signs it with HMAC-SHA256 using
the base64-decoded secret (the part after `whsec_`), base64-encodes the result, and sends one or
more space-separated `v1,<signature>` entries. Use the official `svix` library, which compares in
constant time. Read the `svix-*` headers, and when `svix-id` is absent fall back to the `webhook-*`
headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`).

```javascript
import { Webhook } from 'svix'; // svix 2.x is ESM-only

const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.TERMINAL_TELEMATICS_WEBHOOK_SECRET).verify(rawBody, {
  'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes

```

```python
from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["TERMINAL_TELEMATICS_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
                     "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

```

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/terminal-telematics-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/terminal-telematics-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/terminal-telematics-webhooks/examples/fastapi/).

Terminal registers endpoints in its dashboard and its docs don't print the signing secret, but
Svix-issued secrets start with `whsec_`. Keep the full `whsec_...` value in
`TERMINAL_TELEMATICS_WEBHOOK_SECRET`. Handlers fail closed: with the variable unset they return
500 instead of accepting anything. A missing header or a bad signature returns 400.

### Hookdeck retries and replays hit the 5-minute window

The `svix` and `standardwebhooks` libraries always enforce a fixed 5-minute timestamp window, and
it can't be configured. Hookdeck retries and replays resend the **original** `svix-timestamp`, so
the library rejects any retry or replay that happens more than 5 minutes after the original
delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in
[references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/terminal-telematics-webhooks/references/verification.md), where the window can be dropped or
widened. Deduplicate on `svix-id` instead of relying on the timestamp.

## Common Event Types

32 events are documented in Terminal's API reference (the list may not be exhaustive). The name is
`type` in the JSON body. The examples handle all of them:

| Event | Triggered When |
| --- | --- |
| `connection.created` | A connection to a provider account is created |
| `connection.completed` | A user finishes the authentication flow |
| `connection.disconnected` | Credentials are invalid and the user must re-authenticate |
| `connection.reconnected` | A disconnected connection is re-authenticated |
| `connection.updated` / `connection.pending_deletion` / `connection.deleted` | A connection changes, is marked for deletion, or has its data deleted |
| `sync.requested` / `sync.started` | A connection sync is queued / starts running |
| `sync.completed` | A sync completes successfully |
| `sync.failed` | A sync fails |
| `connection.first_sync_completed` | A connection's first successful sync completes |
| `delivery.requested` / `.started` / `.completed` / `.failed` | A data delivery (for example to S3) moves through its states |
| `issue.reported` / `issue.resolved` | A connection issue is reported or resolved |
| `provider.availability_updated` | A provider's availability changes (outage and recovery); not tied to a connection |
| `unsupported_provider.requested` | A customer requests an unsupported provider in Link |
| `link.analytics_event_emitted` | A user performs a tracked action in the Link flow |
| `vehicle.added` / `.modified` / `.removed` | A vehicle changes (also `driver.*` and `trailer.*`) |
| `safety_event.added` / `safety_event.modified` | A safety event is recorded or updated |

See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/terminal-telematics-webhooks/references/overview.md) for the `detail` keys of each event and the
payload shape.

## Environment Variables

```bash
# Signing secret of the webhook endpoint (Svix format, starts with whsec_)
TERMINAL_TELEMATICS_WEBHOOK_SECRET=whsec_xxxxx

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 terminal-telematics --path /webhooks/terminal-telematics

```

Register the tunnel URL as a webhook endpoint in the Terminal dashboard, then trigger an event
(for example, connect a test provider account or request a sync) to see it arrive.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/terminal-telematics-webhooks/references/overview.md) - Terminal webhook concepts, events, payload shape, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/terminal-telematics-webhooks/references/setup.md) - Register an endpoint, get the secret, enable event types
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/terminal-telematics-webhooks/references/verification.md) - Svix verification details, header fallback, manual verifier, timestamp window