Webhooks & events

Your other systems should not have to poll Fleetlane to find out what happened. Fleetlane sends events as they occur, to endpoints you choose. There are two sources. Fleetlane itself reports changes to claims, vehicles, dealerships and dealership users. The lifecycle engine reports on the policies that move those records from one status to the next. Both use the CloudEvents 1.0 format, so one receiver can handle both.

Fleetlane events

Subscribing

Administrators manage subscriptions under Settings › Integrations › Webhooks. Each webhook has:

a delivery URL, either a full address or a path on a configured external system
one or more event types
optional custom headers and an optional signing secret
an active switch, for pausing it without deleting it

Webhooks belong to a lane: a test lane’s events go only to the webhooks set up in that lane.

Before relying on a webhook, press Test on its page. Fleetlane sends a test event to the delivery URL, with the same headers and signature as a real delivery, and shows the HTTP status and response your endpoint returned. The attempt also appears in the webhook’s delivery log.

Event types

Event type	Sent when
`com.fleetlane.claim.created`	A claim is created, by any route
`com.fleetlane.claim.updated`	A claim’s business data changes, including its status, claim type, dealership, vehicle, cause or defect code, repair date, mileage or custom fields
`com.fleetlane.claim.items_changed`	A claim item is added, changed or removed
`com.fleetlane.claim.evidence_changed`	An attachment is uploaded to a claim or removed from it
`com.fleetlane.claim.discussion_changed`	A message is posted, edited or removed in a claim’s discussion
`com.fleetlane.vehicle.created`	A vehicle is created, by any route
`com.fleetlane.vehicle.updated`	A vehicle’s data changes, including its status, VIN, model, registration, in-service date, mileage or custom fields
`com.fleetlane.vehicle.evidence_changed`	An attachment is uploaded to a vehicle or removed from it
`com.fleetlane.vehicle.discussion_changed`	A message is posted, edited or removed in a vehicle’s discussion
`com.fleetlane.business_partner.changed`	A dealership is created with a dealer partner, its partner changes, or its profile is saved. Sent for dealer partners only
`com.fleetlane.dealership.changed`	A dealership is created, or its code, name or dealer partner changes
`com.fleetlane.dealership_user.assigned`	A user is invited to a dealership, or their role or access window there is saved
`com.fleetlane.dealership_user.removed`	A user is removed from a dealership
`com.fleetlane.material_type.changed`	A material type priced from the ERP is created, or its code or name changes

What a delivery looks like

Each delivery is an HTTP POST with Content-Type: application/cloudevents+json. The data object says which claim or vehicle changed. It also carries a short summary of the change. Your system can then fetch whatever else it needs.

{
  "specversion": "1.0",
  "id": "6f0d3c1e-8a52-4b7e-9d3f-2c41a7e5b901",
  "type": "com.fleetlane.claim.updated",
  "source": "/fleetlane/your-tenant",
  "time": "2026-09-15T02:14:07.512Z",
  "datacontenttype": "application/json",
  "data": {
    "aggregateType": "CLAIM",
    "aggregateId": "0b8e5a2d-3f61-4c9a-a0d7-51e2c6b4f8a3",
    "payload": {
      "claimId": "0b8e5a2d-3f61-4c9a-a0d7-51e2c6b4f8a3",
      "claimNumber": "CLM-004211",
      "workflowTracks": [
        {
          "role": "dealer",
          "matrixId": "5d2c7e10-4b8a-4f3e-9c61-0a7b3e8f2d94",
          "matrixCode": "warranty_dealer",
          "matrixVersion": 3,
          "currentStatus": { "code": "SUBMITTED", "name": "Submitted" },
          "statusObservedAt": "2026-09-15T02:14:07.512Z"
        }
      ]
    }
  }
}

Claim events carry the claim’s id, number and workflow tracks: one entry per track, with its role, its policy and the status it is at. Item events report the item and whether it was added, updated or deleted. Evidence events report the attachment and whether it was uploaded or removed. Vehicle events carry the vehicle’s internal number, VIN and workflow tracks. Created and item events of records loaded by a data migration also carry reason: "DATA_MIGRATION".

time is when the change happened, not when it was sent, so a retry carries the same time.

Dealership and material type events

Dealership and material type events carry the whole record as it stood when it changed, so your system does not need to fetch anything. Every field is present, and a field with no value is null.

Event type	`payload` fields
`com.fleetlane.business_partner.changed`	`ref` (the partner number), `name`, `email`, `phone`, `tax_number`, `street`, `city`, `postal_code`
`com.fleetlane.dealership.changed`	`code`, `name`, `partner_number`
`com.fleetlane.dealership_user.assigned` and `.removed`	`user_id`, `email`, `name`, `dealership_code`, `partner_number`, `role_code`, `valid_from`, `valid_to`
`com.fleetlane.material_type.changed`	`code`, `name`

The partner number is the key your ERP already uses for the dealer, and the address is the partner’s primary one. An assignment event describes the assignment as it now stands, so treat it as an insert or update of that user at that dealership. A removal describes the assignment as it was just before it was removed. Users of the manufacturer’s own organization are assigned to its headquarters dealership. Dealerships and partners are never deleted. A material type event lets your ERP keep the material type as a product category; types not priced from the ERP are not sent.

{
  "specversion": "1.0",
  "id": "2d4f7b8e-1c3a-4e6f-9b0d-5a7c9e1f3b24",
  "type": "com.fleetlane.business_partner.changed",
  "source": "/fleetlane/your-tenant",
  "time": "2026-10-01T03:20:11.204Z",
  "datacontenttype": "application/json",
  "data": {
    "aggregateType": "BUSINESS_PARTNER",
    "aggregateId": "7c1e9a4d-2b6f-4d8a-a3e5-9f0b2c4d6e81",
    "payload": {
      "ref": "BP016",
      "name": "Northside Motors",
      "email": "[email protected]",
      "phone": "+61 7 5555 0100",
      "tax_number": null,
      "street": "12 Main Street",
      "city": "Brisbane",
      "postal_code": "4000"
    }
  }
}

Signing

If you set a signing secret, every delivery includes X-Webhook-Signature: sha256=<hex>. The hex value is the HMAC-SHA256 of the raw request body, keyed with your secret as-is. Fleetlane and the lifecycle engine use the same signing convention. Your receiver computes the same value over the bytes it received and rejects the request if they differ. Check the signature before parsing the JSON. You can rotate the secret from the webhook’s page.

For a relative URL, delivery uses the bound external system’s base URL and authentication. A full HTTP(S) URL is sent without that system’s authentication, even if the webhook stores a binding. A signing secret is optional in either case; when configured, the signature is included alongside other delivery headers.

Retries and the delivery log

A delivery succeeds when your endpoint answers with a 2xx status. Any other status, or a network error, counts as a failure. Failed deliveries are retried automatically, up to four attempts in total. Timeouts, connection errors, 5xx, 408 and 429 responses are retried. Any other 4xx response is final at once, because resending the same request would fail the same way.

Each webhook is delivered and retried on its own. If one of your endpoints is down, the others still receive the event on time, and a retry goes only to the endpoint that failed.

A retry sends the event again with the same id, and an event can occasionally reach your endpoint more than once. Treat id as the key for spotting duplicates.

Each webhook’s page shows its delivery log. The log lists every attempt, successful or failed, with the event type, the attempt number, the HTTP status, the response body or error, and the time taken. Its success and failure counts give a quick view of how reliable the endpoint has been. Failed deliveries also appear in Settings › Integrations › Traffic with the event type and the record concerned.

sequenceDiagram
  participant V as Fleetlane
  participant R as Your endpoint
  V->>V: A record changes, one delivery queued per webhook
  V->>R: POST CloudEvent with X-Webhook-Signature
  alt 2xx response
    R-->>V: Accepted
    V->>V: Record success in the delivery log
  else Error or no response
    R-->>V: Failure
    V->>V: Record failure in the delivery log and Traffic
    V->>R: Retry this webhook only, with the same id
  end

Lifecycle engine events

The lifecycle engine, which runs the policies behind every status change, publishes its own events. Fleetlane relies on them to stay in step, and your systems can subscribe to them too.

Event type	Meaning
`com.amonsul.entity.locked`	A lifecycle run has started on a claim or vehicle, and the record is locked while it runs
`com.amonsul.entity.changes`	An action finished and was recorded, or a record was first registered with the engine
`com.amonsul.entity.ready`	A run reached its result: the record’s status transition and the action that produced it
`com.amonsul.entity.unlocked`	The record was released, either because the run completed or because its lock expired
`com.amonsul.sequence.completed`	A sequence of actions finished, with its final status transition
`com.amonsul.entity-type.policy.changed`	An entity type’s policy assignment changed in a lane

A strict, published contract

Every lifecycle event has a published JSON Schema (Draft 2020-12), and its dataschema attribute holds that schema’s URL. Published schemas are never edited. Any change to a payload gets a new version at a new URL, so a receiver built against one version keeps working.

Payloads use snake_case names, and every declared field is always present. A field with no value is sent as null, never left out. Every entity.* and sequence.* event carries the same identifying fields:

entity_id and entity_type
external_id, which is the claim’s or vehicle’s identifier in Fleetlane
entity_name
run_id
sequence_id, sequence_code and sequence_name

The policy change event concerns an entity type, not a single record. Its data is entity_type, previous_policy, policy and changed_at, where each policy is { via, code, version } (via is direct or composite), or null when none was assigned.

Status changes appear once, as a status_transition with the previous and current status. The action’s outcome appears once, as an action_log entry.

{
  "specversion": "1.0",
  "id": "msg-1:com.amonsul.entity.ready:41",
  "type": "com.amonsul.entity.ready",
  "time": "2026-09-14T00:00:04.000Z",
  "datacontenttype": "application/json",
  "data": {
    "entity_id": "entity-1",
    "external_id": "claim-1",
    "entity_type": "claim",
    "entity_name": "CLM-0001",
    "run_id": "run-1",
    "sequence_code": "pay_claim",
    "status_transition": {
      "updated": true,
      "previous": { "code": "APPROVED", "name": "Approved" },
      "current": { "code": "PAID", "name": "Paid" }
    }
  }
}

The example is abridged: source, dataschema, the full status objects and action_log are left out. The published schema defines the complete shape.

Signing, filtering and retries

Signature. With a signing secret set, each delivery carries X-Webhook-Signature: sha256=<hex>, the HMAC-SHA256 of the exact request body, plus X-Webhook-ID and X-Webhook-Attempt.
Filters. A subscription can be narrowed by entity_id, external_id, entity_type, run_id, sequence_code or change_kind.
Retries. Timeouts, connection errors, 5xx, 408 and 429 responses are retried, up to three attempts in total. Other client errors, including 401 and 403, are not retried.
Resending. A failed delivery can be resent later, unchanged, with the same id, time and data.