EonsFleet Webhook Documentation

Register a webhook endpoint

Webhook management endpoints are separate from inbound provider webhooks. They live under /api/v1/webhooks and require normal API authentication.

Authorization: Bearer <access_token>
X-Request-Type: client

# Create a webhook endpoint
POST /api/v1/webhooks
Authorization: Bearer <access_token>
X-Request-Type: client
Content-Type: application/json

{
  "name": "Production operations webhook",
  "url": "https://example.com/eonsfleet/webhooks",
  "description": "Receives trip and incident events",
  "events": [
    "trip.started",
    "trip.completed",
    "incidents.created"
  ],
  // optional — omit both to get today's payload contract with no per-event filtering
  "payload_version": "2026-01-01",
  // optional — defaults to the account-wide location.updated cadence when omitted
  "location_throttle_seconds": 30,
  "subscriptions": [
    {
      "event_type": "trip.started",
      "filters": { "vehicle_ids": [101, 102] }
    }
  ]
}

# 201 Created
{
  "message": "Webhook endpoint registered",
  "data": {
    "id": 12,
    "public_id": "wh_01JABCXYZQRS7T8U9V0WXYZ12",
    "name": "Production operations webhook",
    "url": "https://example.com/eonsfleet/webhooks",
    "description": "Receives trip and incident events",
    "events": ["trip.started", "trip.completed", "incidents.created"],
    "payload_version": "2026-01-01",
    "location_throttle_seconds": 30,
    "status": "active",
    "last_delivery_at": null,
    "last_delivery_status": null,
    "success_rate_30d": null,
    "failure_count": 0,
    "last_failure_at": null,
    "created_at": "2026-08-06T08:00:00.000000Z",
    "updated_at": "2026-08-06T08:00:00.000000Z",
    "secret_key": "whsec_STORE_THIS_ONCE"
  }
}

Required permissions

Every webhook endpoint is gated by role-based access control. A user or API key without the right permission gets a 403, regardless of authentication being otherwise valid.

# 403 Forbidden — missing permission
{
  "message": "Unauthorize access"
}

Verify every delivery

Each delivery includes a timestamp, event slug, and HMAC-SHA256 signature. The signature input is timestamp + "." + rawBody.

// Node.js / Express signature verification
import crypto from "crypto";

function verifyEonsFleetWebhook(req, secret) {
  const timestamp = req.header("X-Eonsfleet-Timestamp");
  const signature = req.header("X-Eonsfleet-Signature") || "";
  const rawBody = req.rawBody;
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Delivery payload shape

Webhook payloads use a small stable envelope with event-specific data in data.

{
  "event": "trip.started",
  "timestamp": "2026-04-03T08:00:00.000000Z",
  "organization_id": 42,
  "data": {
    "id": 1001,
    "reference": "TRIP-2026-1001",
    "vehicle_id": 3,
    "driver_id": 5,
    "status": "started"
  }
}

Device-only telemetry: no vehicle required

If you register a device (by IMEI) without linking it to a Vehicle record in EonsFleet — e.g. you're reselling tracking hardware and your own software is the fleet-management layer — location.updated still fires. vehicle_id is simply null; imei is always present on every location.updated delivery (both payload versions) so you can identify the physical unit either way. driver_id stays null too, since it's resolved from an in-progress Trip, which requires a Vehicle.

# location.updated — payload_version: 2026-01-01 (default)
{
  "event": "location.updated",
  "timestamp": "2026-08-07T14:22:00.000000Z",
  "organization_id": "42",
  "data": {
    "vehicle_id": null,
    "imei": "861100234567890",
    "lat": 6.5244,
    "lng": 3.3792,
    "speed": 35,
    "heading": 180,
    "timestamp": "2026-08-07T14:22:00.000000Z",
    "driver_id": null,
    "ignition": "on",
    "movement": "moving"
  }
}

# location.updated — payload_version: 2026-09-01 (enriched)
{
  "event": "location.updated",
  "timestamp": "2026-08-07T14:22:00.000000Z",
  "organization_id": "42",
  "data": {
    "vehicle_id": null,
    "imei": "861100234567890",
    "lat": 6.5244,
    "lng": 3.3792,
    "speed": 35,
    "heading": 180,
    "timestamp": "2026-08-07T14:22:00.000000Z",
    "driver_id": null,
    "ignition": "on",
    "movement": "moving",
    "odometer_km": 12345.6,
    "fuel_level_percent": 71.5,
    "fuel_level_liters": 42.0,
    "fuel_rate": 2.1,
    "altitude": 45,
    "satellites": 9,
    "gps_confidence": 0.95
  }
}

Payload formats by event

Every webhook delivery uses the same envelope. The data object changes by event type, and the examples below show the exact field names client developers should parse.

{
  "event": "trip.started",
  "timestamp": "2026-04-03T08:00:00.000000Z",
  "organization_id": 42,
  "data": {
    "id": 1001,
    "reference": "TRIP-2026-1001",
    "vehicle_id": 3,
    "driver_id": 5,
    "status": "started"
  }
}

{
  "event": "incidents.created",
  "timestamp": "2026-04-03T10:00:00.000000Z",
  "organization_id": 42,
  "data": {
    "id": 10,
    "reference": "INC-2026-0010",
    "type": "collision",
    "status": "open",
    "priority": "high",
    "date": "2026-04-03"
  }
}

{
  "event": "maintenance.assigned",
  "timestamp": "2026-04-03T09:00:00.000000Z",
  "organization_id": 42,
  "data": {
    "id": 7,
    "vehicle_id": 3,
    "status": "assigned",
    "type": "preventive"
  }
}

{
  "event": "geofence.alert",
  "timestamp": "2026-04-03T08:15:00.000000Z",
  "organization_id": 42,
  "data": {
    "device_id": "IMEI123456789",
    "message": "Vehicle entered Restricted Zone",
    "in_geofenced_area": true
  }
}

{
  "event": "device.status_changed",
  "timestamp": "2026-04-03T07:55:00.000000Z",
  "organization_id": 42,
  "data": {
    "device_id": 18,
    "imei": "IMEI123456789",
    "is_online": false,
    "was_online": true
  }
}

{
  "event": "alert.speeding",
  "timestamp": "2026-04-03T08:20:00.000000Z",
  "organization_id": 42,
  "data": {
    "vehicle_id": 3,
    "vehicle_name": "Toyota Hilux",
    "speed_kmh": 85.0,
    "speed_limit": 60,
    "detected_at": "2026-04-03T08:20:00Z"
  }
}

{
  "event": "alert.idling",
  "timestamp": "2026-04-03T08:25:00.000000Z",
  "organization_id": 42,
  "data": {
    "vehicle_id": 3,
    "imei": "IMEI123456789",
    "detected_at": "2026-04-03T08:25:00Z"
  }
}

{
  "event": "test.ping",
  "timestamp": "2026-04-03T08:00:00.000000Z",
  "organization_id": 42,
  "data": {
    "message": "This is a test delivery from EonsFleet."
  }
}

Retries, dead-lettering, and endpoint health

Deliveries run on the webhooks queue. What happens after a failed attempt depends on why it failed — some responses are retried, some never are.

Dead-lettering

A delivery is dead-lettered when EonsFleet has given up on it — whether that took one attempt (permanent failure, SSRF block) or three (exhausted retries). This is recorded as a dead_lettered_at timestamp, separate from status, so you can distinguish "still might succeed" from "definitely won't without intervention." Query it directly with ?status=dead_lettered on either deliveries endpoint below — that filters on dead_lettered_at IS NOT NULL, which is a superset of deliveries whose status column happens to read failed.

Attempt history

A delivery log row (returned by the two deliveries endpoints) is overwritten on every retry — it always reflects only the latest attempt. To see every individual try — including the exact request headers sent, the raw response, and per-attempt timing — use the delivery attempts endpoint. Attempt rows are write-once and never change after being recorded.

# GET /api/v1/webhooks/12/deliveries/80/attempts — 200 OK
{
  "message": "success",
  "data": {
    "attempts": [
      {
        "id": 1,
        "public_id": "att_01JABCXYZQRS7T8U9V0WXYZ12",
        "attempt_number": 1,
        "response_status": 503,
        "response_body": "Service Unavailable",
        "error_type": "http_5xx",
        "error_message": null,
        "latency_ms": 320,
        "started_at": "2026-08-06T08:00:59.000000Z",
        "completed_at": "2026-08-06T08:00:59.320000Z"
      }
    ],
    "pagination": { "current_page": 1, "per_page": 15, "total": 1, "last_page": 1 }
  }
}

error_type is one of ssrf_blocked, http_4xx, http_5xx, rate_limited, connection_error, or null on a successful attempt.

# Retry a single delivery
POST /api/v1/webhooks/12/deliveries/80/retry
Authorization: Bearer <access_token>
X-Request-Type: client

# 422 if it was already delivered
{ "message": "Delivery was already successful — retry is not needed" }

Replay many deliveries at once

To resend more than one delivery — e.g. after fixing a receiving endpoint that was down for an hour — queue a bulk replay instead of retrying one at a time. A replay never modifies the original delivery records; it creates a brand-new delivery per match, linked back to the original, and queues each one for a fresh attempt.

# Queue a replay of everything dead-lettered for one endpoint this week
POST /api/v1/webhook-replays
Authorization: Bearer <access_token>
X-Request-Type: client
Content-Type: application/json

{
  "webhook_endpoint_id": 12,
  "status": "dead_lettered",
  "date_from": "2026-08-01"
}

# 202 Accepted
{
  "message": "Replay queued",
  "data": {
    "id": 1,
    "public_id": "rpl_01JABCXYZQRS7T8U9V0WXYZ12",
    "webhook_endpoint_id": 12,
    "filters": { "webhook_endpoint_id": 12, "status": "dead_lettered", "date_from": "2026-08-01" },
    "total_count": 3,
    "replayed_count": 0,
    "status": "pending",
    "started_at": null,
    "completed_at": null
  }
}