Webhooks

Creating an endpoint

1. Open Settings → Webhooks.
2. Click New webhook, paste a publicly-reachable HTTPS URL.
3. Pick the events you care about. You can subscribe to a single event (e.g. trip.completed), an entire category (e.g. telematics.*), or everything (*).
4. Save. The created endpoint reveals a hex secret once — store it somewhere safe.

Envelope

Every delivery POSTs the same JSON shape:

{
  "id": "wd_abc...",
  "event": "trip.completed",
  "tenantId": "tnt_xxx",
  "scope": "tenant",
  "occurredAt": "2026-05-11T07:32:14.211Z",
  "correlationId": "...",
  "data": {
    "tripId": "trp_xxx",
    "reference": "TRP-2026-XYZ123",
    "status": "completed"
  }
}

Signing

Every request includes these headers — verify them before doing any work:

• X-Fleetonomy-Signature — t=<unix-seconds>,v1=<hex>
• X-Fleetonomy-Timestamp — same seconds value
• X-Fleetonomy-Event — event name
• X-Fleetonomy-Delivery — endpoint-scoped monotonic sequence
• X-Fleetonomy-Scope — platform or tenant
• X-Fleetonomy-Tenant — tenant id (omitted for platform events)

The signature is computed as:

v1 = hmac_sha256(secret, `${timestamp}.${rawBody}`)
header = `t=${timestamp},v1=${v1.toString("hex")}`

Reject requests where |now - timestamp| > 5 minutes to mitigate replay attacks. Use a constant-time compare for the hex signature.

// Node example
import crypto from "node:crypto";

export function verifyFleetonomy(headers, rawBody, secret) {
  const sig = headers["x-fleetonomy-signature"];
  const tsHeader = headers["x-fleetonomy-timestamp"];
  const ts = Number(tsHeader);
  if (!sig || !ts) return false;
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
  const provided = /v1=([a-f0-9]+)/.exec(sig)?.[1] ?? "";
  return (
    provided.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(expected))
  );
}

Delivery + retries

Endpoints must respond 2xx within 10 seconds. Any other response is treated as a failure and retried with exponential backoff. Default schedule: 10s, 60s, 5m, 30m, 1h, 4h.

The Fleetonomy admin UI shows delivery history per endpoint with response codes and snippets. From there you can re-fire any delivery, rotate the secret or temporarily disable the endpoint.

Categories

• tenant.*
• user.*
• subscription.* + invoice.*
• vehicle.*
• driver.*
• trip.*
• telematics.*
• compliance.*
• fuel.* + maintenance.*
• payment.*
• security.*
• api.* + mcp.*
• system.*