Fleetr Help Centre
Fleetr customer guide
On this page

Event Forwarding and Webhooks

Let your systems respond when your fleet reports something new.

Last updated: .

Event forwarding lets another system receive selected fleet events as signed HTTPS requests. Use it for a customer dashboard, operational integration, or automation that reacts to recorded fleet activity. REST requests retrieve data on demand; forwarding delivers new events to a configured receiver.

Create a Forwarding Endpoint

  1. Open Account → Integrations → Event forwarding with an authorised user and eligible plan.
  2. Add an endpoint with a recognisable name and a public HTTPS destination URL.
  3. Select at least one event type and enable the endpoint.
  4. Save and copy the generated signing secret immediately; it is shown only once.
  5. Configure your receiving system to verify the signed requests.
  6. Use Test and confirm the receiver actually processed the test before depending on production deliveries.

An account can configure up to five forwarding endpoints. Localhost and private-network addresses are not suitable destinations. Use an endpoint that accepts requests directly; redirects are not followed.

Events You Can Subscribe To

Event groupEvent types
Locationposition.update
Cost centerscost_center.updated, cost_center.archived, cost_center.restored
Journeystrip.start, trip.end, journey.updated, journey.deleted
Geofencesgeofence.enter, geofence.exit, geofence.dwell
Ignitionignition.on, ignition.off
Idlingidling.start, idling.end
Device connectivitydevice.offline
Device alertsalert.sos, alert.towing, alert.vibration
Immobiliser stateimmobilizer.on, immobilizer.off

Subscribe to the events your workflow actually uses. The existence of an event type does not mean every tracker can detect it; event delivery depends on compatible devices and received data.

Understand the Delivery Format

Each JSON envelope includes event_id, type, version, occurred_at, account_id, and a data object whose fields depend on the event. The current envelope version is 1. Test deliveries include data.test: true; keep them separate from real operational events.

Fleetr supplies these headers:

HeaderPurpose
X-Fleetr-EventEvent type
X-Fleetr-Event-IdIdentifier used to recognise duplicate deliveries
X-Fleetr-TimestampUnix timestamp for this delivery attempt
X-Fleetr-SignatureHex-encoded HMAC-SHA256 signature

Verify the signature using your endpoint secret and the exact bytes of timestamp + . + raw request body. Compare signatures using a constant-time comparison. Preserve the raw body for verification instead of parsing and re-encoding JSON first. Apply an appropriate timestamp freshness check in the receiver and deduplicate processing by event_id.

Geofence Entries, Exits and Dwell

geofence.enter and geofence.exit are sent once for each crossing of each geofence, including zones a connected app such as Dispatchr manages in Fleetr. The data names the geofence: geofence_id, geofence_name, and, for a connected app's zones, geofence_external_ref (the app's own zone id) and geofence_source (for example dispatchr). Both are null for geofences drawn in Fleetr. The data also carries vehicle_id, vehicle_identification, device_id, lat, lng, bearing, speed_kmh and within_schedule. occurred_at is the GPS time of the crossing. Crossings outside a geofence's schedule are still forwarded with within_schedule: false; schedules only decide who Fleetr notifies. See Keep Connected-App Zones in Sync for an example.

geofence.dwell is sent once per stay when a vehicle stays inside a geofence that has a dwell time (dwell_minutes, set through the integration geofence API) for that long. It carries the same geofence and vehicle fields, plus entered_at (the GPS time of the entry that started the stay) and dwell_minutes. occurred_at is entered_at plus dwell_minutes, duration is the same length in seconds, and lat/lng are where the vehicle entered. A dwell is always sent before the exit that ends its stay. After the exit, the next entry starts a new stay that can dwell again.

Late and Corrected Trip Events

Trackers that lose signal store their positions and send them when they reconnect. When those positions show that a trip really started or ended at a different time, Fleetr corrects the trip and forwards the correction:

  • The envelope carries late: true. Envelopes for events reported as they happened do not include the field.
  • occurred_at is when the event really happened, which may be hours before delivery.
  • A trip.start or trip.end that moved includes data.previous_occurred_at, the time it was first reported with.
  • A trip.start or trip.end that did not happen includes data.retracted: true and the time it was first reported with; remove it from your records.
  • Corrections look back at most 48 hours and never cover trips recorded before the account last changed what ends a trip.

Corrections are not sent as push, SMS, WhatsApp or email alerts. Order events by occurred_at, never by arrival.

Keep Recorded Journeys in Sync

Select Journey record updated (journey.updated) and Journey record removed (journey.deleted) on your forwarding endpoint when another system mirrors Fleetr's recorded journeys. Existing endpoints keep their current selections; new types are not enabled automatically. These notifications also cover changes that do not create another trip.start or trip.end: final distance/fuel measurement, corrected journey boundaries, restoration, and retirement of an overlapping or phantom journey.

The following example uses sample identifiers. A new, measured, corrected or restored record sends journey.updated:

{
  "event_id": "89882ce7-fc1c-4a61-8b29-147e80eca654",
  "type": "journey.updated",
  "version": 1,
  "occurred_at": "2026-10-21T09:00:00+00:00",
  "account_id": 17,
  "data": {"journey_id": 501, "vehicle_id": 31, "revision": 2, "deleted": false}
}

A retired record sends the same shape with type: "journey.deleted" and data.deleted: true. Its journey ID identifies the removed source record. When a correction replaces one journey with another, expect a removal for the old ID and an update for the new ID. The new journey has its own revision sequence.

The payload is a request to refresh authoritative data. It contains no route coordinates, driver details or measured totals. Fetch GET /api/vehicles/{vehicle_id}/journeys with your account API token and explicit X-Account-ID, follow pagination, and reconcile your Fleetr mirror. A first update can describe a saved journey whose measurements are still unknown; a later update announces the finished measurements. Refer to the interactive API reference and OpenAPI specification for the envelope schema.

Deduplicate by event_id; revision increases for semantic changes to one journey and does not increase merely because an unchanged build is retried. Different journeys' revisions cannot be compared. Deliveries may arrive out of order, so retain the newest revision seen for each journey and refetch current state rather than restoring an old payload. occurred_at is when the recorded state changed, not the journey's departure or arrival time. Do not delete your own dispatch work, attendance, invoices or other operational records because a mirrored Fleetr journey was retired.

Recorded-journey changes are retained transactionally until the queue accepts them; the production scheduler recovers pending changes every minute. A rolled-back correction produces no committed notification. If queue acceptance is ambiguous, recovery can send the same event again, with the same event ID. After acceptance, the normal five-attempt delivery policy below applies. This is not a replay service for historical journeys: with no enabled matching subscriber, pending changes are consumed without delivery; enabling these types later does not replay that history. Perform an initial API sync when first connecting and keep periodic reconciliation as a backstop.

Retries and Delivery Health

Failed deliveries can be attempted up to five times, with backoff intervals of 30 seconds, 2 minutes, 10 minutes, and 30 minutes between attempts. The event ID remains the same across retries. Handle duplicates safely and return a successful response promptly after accepting the event; the delivery timeout is 15 seconds.

Review the endpoint's delivery health when events are missing. Check that it is enabled, subscribed to the event, reachable over HTTPS, and verifying the current secret. If the test shows a support reference, include that reference when asking for help. An exhausted retry sequence is not a promise of indefinite redelivery.

Edit, Pause, Rotate, or Remove an Endpoint

Edit the destination and event selection when requirements change. Pause an endpoint to stop forwarding while retaining its configuration, then resume it when ready. Pausing or removing an endpoint can stop queued deliveries as well; do not assume paused events will be replayed later.

Rotate the signing secret if it is lost or compromised and update the receiver immediately: there is no overlap period for the old secret. Delete an endpoint when the integration is no longer used. These controls manage event delivery and do not remove recorded vehicle activity.

Refresh Cost Centres After Archive and Restore

Select the three Cost centers event types explicitly; existing endpoints do not opt in automatically. Ordinary cost-centre creation, edits, archival and restoration capture durable hints with the source change. A scheduled drain queues them every minute; failed queue acceptance remains recoverable. Bulk account maintenance is outside this model-write notification contract. There is no historical replay for types with no matching subscriber when drained.

A synthetic archive example:

{"event_id":"675d51e2-d66c-4ef1-bcc1-1e8240065977","type":"cost_center.archived","version":1,"occurred_at":"2026-10-21T12:00:00+00:00","account_id":123,"data":{"cost_center_id":456,"revision":2,"archived":true}}

cost_center.updated covers new or edited records; cost_center.restored identifies an active restored record. Verify the signature over the unchanged request body as above, deduplicate event_id, and tolerate duplicates and unordered arrival. Revisions increase independently for each cost centre. Fetch all pages of GET /api/cost-centers with the matching account header to reconcile current state. Preserve historical references; do not delete consumer records or assume a missing row was archived. Periodic polling remains the fallback if event types are not enabled or delivery is delayed.