Webhook Payload Reference

Every webhook delivery is an HTTP POST with a Content-Type: application/json body. The body is a versioned object: the top-level v field is the payload schema version, currently 1. Fleetera will not make breaking changes to a published version — new fields may be added, but existing fields keep their meaning. If the schema ever changes incompatibly, the version number changes with it.

Write your receiver to tolerate additional fields it does not recognize, and to branch on the top-level type (alert.triggered vs. alert.resolved). This keeps your integration working as Fleetera adds detail to the payload over time.

The examples on this page use fleetera.example.com where your payloads carry the address you use to sign in to Fleetera.

Example: alert triggered

{
  "v": 1,
  "type": "alert.triggered",
  "id": "9f2a7c1b-3e84-4d56-9a0f-1c7b2e5d8a40",
  "timestamp": "2026-06-10T09:42:17.512Z",
  "tenantId": "7c1e0b8f-2c6f-4f57-bb20-0a1e4d9a9d3a",
  "alert": {
    "eventId": "5d8a40f2-9f2a-4c1b-3e84-2e5d1c7b9a0f",
    "status": "triggered",
    "severity": "critical",
    "triggeredAt": "2026-06-10T09:42:17.000Z",
    "resolvedAt": null,
    "triggerValue": 87.4,
    "threshold": 80,
    "rule": {
      "id": "1c7b2e5d-9a0f-4d56-3e84-9f2a7c1b8a40",
      "name": "Gearbox over-temp",
      "type": "threshold"
    },
    "labels": {
      "assetId": "2e5d1c7b-5d8a-40f2-9f2a-4c1b3e849a0f",
      "variableKey": "gearbox_temp",
      "assetName": "Gearbox 7",
      "siteId": "8a40f29f-2a7c-1b3e-849a-0f1c7b2e5d8a",
      "assetCategoryAlias": "ambient_system",
      "connectorId": "4d569f2a-7c1b-3e84-9a0f-1c7b2e5d8a40",
      "unit": "degC"
    },
    "externalRefs": []
  },
  "links": {
    "event": "https://fleetera.example.com/alerts/events/5d8a40f2-9f2a-4c1b-3e84-2e5d1c7b9a0f"
  }
}

Example: alert resolved

An alert.resolved message is sent when the alert clears, if the channel has resolved notifications enabled. It carries the same id-as-idempotency-key contract and the same labels, with status: "resolved" and a non-null resolvedAt. In this example someone linked a work order to the alert while it was open, so the resolve carries it in externalRefs:

{
  "v": 1,
  "type": "alert.resolved",
  "id": "c3b9e2d7-a4f1-4c8b-0c5b-3f9a7c2b8e1d",
  "timestamp": "2026-06-10T10:05:44.218Z",
  "tenantId": "7c1e0b8f-2c6f-4f57-bb20-0a1e4d9a9d3a",
  "alert": {
    "eventId": "5d8a40f2-9f2a-4c1b-3e84-2e5d1c7b9a0f",
    "status": "resolved",
    "severity": "critical",
    "triggeredAt": "2026-06-10T09:42:17.000Z",
    "resolvedAt": "2026-06-10T10:05:43.000Z",
    "triggerValue": 76.1,
    "threshold": 80,
    "rule": {
      "id": "1c7b2e5d-9a0f-4d56-3e84-9f2a7c1b8a40",
      "name": "Gearbox over-temp",
      "type": "threshold"
    },
    "labels": {
      "assetId": "2e5d1c7b-5d8a-40f2-9f2a-4c1b3e849a0f",
      "variableKey": "gearbox_temp",
      "assetName": "Gearbox 7",
      "siteId": "8a40f29f-2a7c-1b3e-849a-0f1c7b2e5d8a",
      "assetCategoryAlias": "ambient_system",
      "connectorId": "4d569f2a-7c1b-3e84-9a0f-1c7b2e5d8a40",
      "unit": "degC"
    },
    "externalRefs": [
      {
        "system": "CMMS",
        "id": "WO-10442",
        "url": "https://cmms.example.com/work-orders/WO-10442"
      }
    ]
  },
  "links": {
    "event": "https://fleetera.example.com/alerts/events/5d8a40f2-9f2a-4c1b-3e84-2e5d1c7b9a0f"
  }
}

Example: KPI rule alert

An alert from a KPI rule carries two more fields: alert.kpi, which names the KPI and the window it evaluated, and links.kpiWindow, which opens that window in Fleetera. The labels describe the KPI rather than a live signal, so variableKey is the KPI's key and connectorId and unit are null.

{
  "v": 1,
  "type": "alert.triggered",
  "id": "e7a1c4d2-6b3f-4e89-a2d5-8f1c0b9e3a76",
  "timestamp": "2026-08-04T00:07:12.338Z",
  "tenantId": "7c1e0b8f-2c6f-4f57-bb20-0a1e4d9a9d3a",
  "alert": {
    "eventId": "b4e2f8a1-7c3d-4a96-8e15-2d9f6c0a1b53",
    "status": "triggered",
    "severity": "warning",
    "triggeredAt": "2026-08-04T00:07:11.000Z",
    "resolvedAt": null,
    "triggerValue": 212.5,
    "threshold": 250,
    "rule": {
      "id": "6a0d3f7e-2b8c-4e51-9d47-c1f5a8e2b039",
      "name": "Plane-of-array irradiance low",
      "type": "kpi_threshold"
    },
    "labels": {
      "assetId": "0f3c9a6e-8d21-4b7f-a5e4-7b2d1c9f4e86",
      "variableKey": "poa_wm2_hourly_avg",
      "assetName": "PV array 3",
      "siteId": "3b7e1d5a-c492-4f08-b6a3-9e0f2d8c1a57",
      "assetCategoryAlias": null,
      "connectorId": null,
      "unit": null
    },
    "kpi": {
      "definitionId": "77777777-7777-4777-8777-777777777777",
      "definitionRevision": 3,
      "kpiKey": "poa_wm2_hourly_avg",
      "windowStart": "2026-08-03T00:00:00.000Z",
      "windowEnd": "2026-08-04T00:00:00.000Z"
    },
    "externalRefs": []
  },
  "links": {
    "event": "https://fleetera.example.com/alerts/events/b4e2f8a1-7c3d-4a96-8e15-2d9f6c0a1b53",
    "kpiWindow": "https://fleetera.example.com/insight/kpis/77777777-7777-4777-8777-777777777777?from=2026-08-03T00%3A00%3A00.000Z&to=2026-08-04T00%3A00%3A00.000Z"
  }
}

Top-level fields

Field	Type	Description
`v`	number	Payload schema version. Currently `1`.
`type`	string	The event type: `alert.triggered` or `alert.resolved`. Matches the `X-Fleetera-Event` header.
`id`	string	The delivery ID. This is also the idempotency key — see below. Matches the `X-Fleetera-Delivery` header.
`timestamp`	string	ISO-8601 instant at which Fleetera dispatched this delivery.
`tenantId`	string	The Fleetera organization (tenant) the alert belongs to.
`alert`	object	The alert detail. See Alert object.
`links`	object	Links into the Fleetera app for this alert. See Links object.

The `id` field is your idempotency key

id identifies the delivery, and it is stable across retries: if Fleetera retries a delivery after a transient failure, the retried request carries the same id (and the same X-Fleetera-Delivery header). Your receiver may therefore see the same id more than once.

Deduplicate on id. Record the IDs you have already processed and treat a repeat as a no-op (or make your handler idempotent some other way). This guarantees that a retry never results in a duplicate ticket, page, or message. Do not dedupe on alert.eventId alone — a trigger and its later resolve share the same eventId.

Alert object

The alert object describes the alert event itself.

Field	Type	Description
`eventId`	string	The alert event ID. The same `eventId` is shared by an alert's trigger and its later resolve.
`status`	string	`triggered` or `resolved`.
`severity`	string	The alert severity: `info`, `warning`, or `critical`.
`triggeredAt`	string	ISO-8601 instant the alert first triggered.
`resolvedAt`	string \| null	ISO-8601 instant the alert resolved, or `null` while the alert is still active.
`triggerValue`	number \| null	The measured value that drove the event, when applicable. `null` for rules where a single value does not apply.
`threshold`	number \| null	The configured threshold the value was compared against, when applicable. `null` for rule types without a single threshold.
`rule`	object	The rule that produced the alert. See Rule object.
`labels`	object	Routing and identity labels for the alert. See Labels object.
`kpi`	object	Present only on alerts from KPI rules, and left out entirely on every other alert. See KPI object.
`externalRefs`	array	The work orders and tickets linked to the alert in Fleetera, oldest first. An empty array when nothing is linked. See External references.

Rule object

Field	Type	Description
`id`	string	The alert rule's ID.
`name`	string	The human-readable rule name, as configured in Fleetera.
`type`	string	The rule type: `threshold`, `duration`, `multi_condition`, `rate_of_change`, `pattern`, or `staleness` for rules on live signals, and `kpi_threshold` or `kpi_staleness` for KPI rules.

Labels object

The labels object carries the identity of the asset and signal the alert fired on. These are the same labels Fleetera routes on internally, so a receiver that forwards alerts into another system (such as PagerDuty or Opsgenie) can re-route on the same identifiers.

Field	Type	Description
`assetId`	string	The asset the alert fired on. Always present.
`variableKey`	string	The variable (signal) key the alert evaluated. On a KPI rule alert, the KPI's key. Always present.
`assetName`	string \| null	The asset's display name, so a receiver can show it without looking the asset up. May be `null`.
`siteId`	string \| null	The site the asset belongs to. May be `null` if unknown for the rule.
`assetCategoryAlias`	string \| null	The asset category alias (for example, `ambient_system`). May be `null`.
`connectorId`	string \| null	The connector that supplied the data. May be `null`, and is always `null` on a KPI rule alert.
`unit`	string \| null	The unit of the measured value (for example, `degC`). May be `null`, and is always `null` on a KPI rule alert.

assetId and variableKey are always present — they are the per-instance identity of the alert. The remaining labels are nullable: a label can be absent for an older or inline rule. Always handle null for assetName, siteId, assetCategoryAlias, connectorId, and unit.

KPI object

Present on alerts from kpi_threshold and kpi_staleness rules. It records which KPI produced the value the alert is about, and which window was evaluated.

Field	Type	Description
`definitionId`	string	The KPI definition the alert is about. Always present.
`definitionRevision`	number \| null	The revision of the definition that computed the value. `null` when the alert does not record one.
`kpiKey`	string \| null	The KPI's key, the same value as `labels.variableKey`. `null` when the alert does not record one.
`windowStart`	string \| null	ISO-8601 start of the window the rule evaluated.
`windowEnd`	string \| null	ISO-8601 end of that window.

windowStart and windowEnd are both set or both null. A kpi_staleness alert reports windows that did not arrive, so it has no window of its own and carries null in both.

External references

People in your organization can link a work order or ticket in another system to an alert. Anyone who can acknowledge alerts can do it on the alert's page: More, then Add reference, then choose the System (or Other and type the System name), and enter the ID and the Link. The alert's Facts then list each one under References, named by its system and ID.

externalRefs carries those references to your receiver:

Field	Type	Description
`system`	string	The system the record lives in, as chosen or typed when it was linked. At most 64 characters.
`id`	string	The record's ID in that system. At most 128 characters.
`url`	string	The link to the record. Always an `https` URL, at most 2048 characters.

An alert holds at most 10 references, and no two share the same system and id. Linking or removing a reference sends no delivery of its own: each delivery carries the list as it stands when that delivery is sent. A trigger normally arrives with an empty list, because nothing has been linked to an alert that has just fired. A resolve carries whatever was linked while the alert was open, so a receiver that opened a ticket can find it and close it.

Links object

The links object carries links into the Fleetera app, so a receiver can put a button or link on the message it builds. Each value is an absolute URL on the address you use to sign in to Fleetera.

Field	Type	Description
`event`	string	Opens the alert's page in Fleetera: its context chart, timeline, facts and deliveries, and the actions the person opening it is allowed to take. Always present.
`kpiWindow`	string	Present only on alerts from KPI rules. Opens the KPI's page with its history chart on the window the rule evaluated. The window travels as the `from` and `to` query parameters, the URL-encoded values of `alert.kpi.windowStart` and `windowEnd`. A `kpi_staleness` alert has no window, so its link has no `from` or `to` and opens the KPI's page in its default view.

Use each link exactly as Fleetera sends it, rather than building it from IDs. Links in deliveries you have already received keep working: an alert link in the older /alerts/events?eventId= form now opens the alert's page.

Webhook Payload Reference

On this page