Agent skill
Terminal Webhooks Skill
Receive and verify Terminal webhooks (withterminal.com, the unified telematics/ELD data API, delivered via Svix). Use when setting up Terminal webhook handlers, debugging svix-signature verification, or handling events like connection.created, sync.completed, sync.failed, vehicle.added, and safety_event.added.
Install this skill
npx skills add hookdeck/webhook-skills --skill terminal-telematics-webhooks
Terminal 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, orconnection.disconnectedevents? - How do I react to
vehicle.added,driver.modified, orsafety_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).
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
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/, examples/nextjs/, 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_. 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, 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_ / 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_ | 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_ | A provider's availability changes (outage and recovery); not tied to a connection |
unsupported_ | A customer requests an unsupported provider in Link |
link.analytics_ | 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 for the detail keys of each event and the payload shape.
Environment Variables
# Signing secret of the webhook endpoint (Svix format, starts with whsec_)
TERMINAL_TELEMATICS_WEBHOOK_SECRET=whsec_xxxxx
Local Development
# 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 - Terminal webhook concepts, events, payload shape, retries
- references/setup.md - Register an endpoint, get the secret, enable event types
- references/verification.md - Svix verification details, header fallback, manual verifier, timestamp window