Alarm Webhook Events

1. Purpose

This document describes alarm webhook event types, payload fields, examples, and estimated wasted fuel formulas.

The webhook is intended for:

• Receiving hardware alarm events reported by devices.
• Receiving business alarm events generated by platform rules.
• Understanding estimated wasted fuel for selected behavior events.

2. Event Types

The webhook currently supports two top-level event types:

hardware_alarm.created
business_alarm.created

The detailed alarm type is provided in:

alarm.alarmType

Subscriptions may be configured at either level:

hardware_alarm.created
business_alarm.created
SPEED
STAY_ACC_ON
FAST_ACCELERATION
business_alarm.created:SPEED
hardware_alarm.created:FAST_ACCELERATION

If a customer subscribes only to a specific alarm type, other alarm events are ignored and no webhook payload is generated for them.

Webhook delivery is also limited by device ownership. The system first loads all enabled webhook configurations, finds the account IDs from those configurations, expands each account to include its child accounts, and caches the device IMEIs covered by those accounts for five minutes. If a webhook is configured on a parent account, devices under all child accounts are covered by that configuration.

First-version webhook alarm messages must include the device IMEI. A batch message may contain multiple alarm IDs and multiple IMEIs. The system first performs a lightweight batch-level cache check. After the alarm records are loaded, it performs a second alarm-level IMEI check. Only alarms whose IMEI is covered by an enabled webhook configuration can generate payloads and be written to the webhook outbox. Other alarms in the same batch are ignored.

3. Alarm Categories

3.1 Hardware Alarms

Hardware alarms are reported by the device.

Possible hardware alarm types include:

LOW_BATTERY
SHAKE
LIGHT_SENSATION
OUTAGE
TURNOVER
CRASH
FAST_ACCELERATION
FAST_DECELERATION
SHARP_TURN
DOOR_OPEN
DOOR_CLOSE
SOS

Important notes:

• A hardware alarm means the device reported that alarm type.
• The webhook does not include raw G-sensor or IMU data.
• The webhook does not include G-force values.
• The webhook does not include crash severity.
• Harsh driving alarms, if present, are device-reported alarm events. They are not calculated from raw acceleration data by this webhook.

3.2 Business Alarms

Business alarms are generated by platform-side rules.

Possible business alarm types include:

SHIFT
SPEED
OUT_FENCE
IN_FENCE
OFFLINE_TIMEOUT
STAY_TIMEOUT
STAY_ACC_ON
ENGINE_ON
ENGINE_OFF

Fuel waste estimation is currently intended mainly for:

SPEED
STAY_ACC_ON
FAST_ACCELERATION
FAST_DECELERATION
SHARP_TURN

Other alarm types are still pushed, but fuel impact is usually marked as not applicable.

4. Payload Format

All text values generated by the webhook are English-only.

Example structure:

{
  "version": "2026-06-21.v1",
  "eventId": "alarm:123457",
  "eventSequence": 123457,
  "eventType": "business_alarm.created",
  "occurredAt": "2026-06-21T10:15:00Z",
  "pushedAt": "2026-06-21T10:22:05Z",
  "accountId": 10001,
  "imei": "868120000000001",
  "device": {
    "imei": "868120000000001",
    "deviceName": "Vehicle A",
    "licenseNumber": "ABC123",
    "vin": "L1234567890",
    "deviceType": "G19"
  },
  "alarm": {
    "alarmId": 123457,
    "alarmType": "SPEED",
    "alarmCode": 12,
    "alarmName": "SPEED",
    "category": "BUSINESS"
  },
  "source": {
    "type": "device_alarm",
    "table": "device_alarm",
    "id": 123457
  },
  "confidence": "high",
  "data": {},
  "fuelImpact": null,
  "explanation": "",
  "formulaVersion": "fuel-estimated-v1"
}

4.1 Field Description

Field	Type	Description
version	string	Webhook payload version.
eventId	string	Unique event ID. Alarm events use alarm:{alarmId}.
eventSequence	number	Stable sequence number for alarm webhook events. For alarm events, this is the alarm record ID and can be used together with occurredAt for business ordering.
eventType	string	Top-level webhook event type.
occurredAt	string	Time when the alarm occurred.
pushedAt	string	Time when the webhook payload was generated for delivery.
accountId	number	Account-level identifier. Receivers can treat it as the customer account or business account to which the event belongs.
imei	string	Stable physical device identifier.
device.imei	string	Device IMEI.
device.deviceName	string	Device name, if configured.
device.licenseNumber	string	License plate number, if configured.
device.vin	string	Vehicle identification number, if configured.
device.deviceType	string	Device type or model name.
alarm.alarmId	number	Alarm record ID.
alarm.alarmType	string	English alarm enum name, such as SPEED.
alarm.alarmCode	number	Numeric alarm code.
alarm.alarmName	string	Same as alarm.alarmType.
alarm.category	string	HARDWARE or BUSINESS.
source	object	Technical source reference for troubleshooting.
confidence	string	Event confidence level.
data	object	Alarm-specific details.
fuelImpact	object	Estimated wasted fuel impact.
explanation	string	English explanation of the event.
formulaVersion	string	Fuel estimation formula version.

5. Example Payloads

5.1 Hardware Alarm Example

{
  "version": "2026-06-21.v1",
  "eventId": "alarm:123456",
  "eventSequence": 123456,
  "eventType": "hardware_alarm.created",
  "occurredAt": "2026-06-21T10:20:00Z",
  "pushedAt": "2026-06-21T10:20:03Z",
  "accountId": 10001,
  "imei": "868120000000001",
  "device": {
    "imei": "868120000000001",
    "deviceName": "Vehicle A",
    "licenseNumber": "ABC123",
    "vin": "L1234567890",
    "deviceType": "G19"
  },
  "alarm": {
    "alarmId": 123456,
    "alarmType": "OUTAGE",
    "alarmCode": 11,
    "alarmName": "OUTAGE",
    "category": "HARDWARE"
  },
  "source": {
    "type": "device_alarm",
    "table": "device_alarm",
    "id": 123456
  },
  "confidence": "high",
  "data": {
    "lat": 22.543096,
    "lng": 114.057865,
    "speedKmh": 0,
    "course": 180,
    "locationType": 1
  },
  "fuelImpact": {
    "applicable": false,
    "reason": "This alarm type is not suitable for fuel waste estimation."
  },
  "explanation": "The vehicle triggered a OUTAGE alarm. This event is mainly used for vehicle safety, device status, or operations management.",
  "formulaVersion": "fuel-estimated-v1"
}

5.2 Overspeed Alarm Example

{
  "version": "2026-06-21.v1",
  "eventId": "alarm:123457",
  "eventSequence": 123457,
  "eventType": "business_alarm.created",
  "occurredAt": "2026-06-21T10:15:00Z",
  "pushedAt": "2026-06-21T10:22:05Z",
  "accountId": 10001,
  "imei": "868120000000001",
  "device": {
    "imei": "868120000000001",
    "deviceName": "Vehicle A",
    "licenseNumber": "ABC123",
    "vin": "L1234567890",
    "deviceType": "G19"
  },
  "alarm": {
    "alarmId": 123457,
    "alarmType": "SPEED",
    "alarmCode": 12,
    "alarmName": "SPEED",
    "category": "BUSINESS"
  },
  "source": {
    "type": "device_alarm",
    "table": "device_alarm",
    "id": 123457
  },
  "confidence": "high",
  "data": {
    "lat": 22.543096,
    "lng": 114.057865,
    "speedKmh": 110,
    "course": 180,
    "locationType": 1,
    "configId": 2001,
    "speedThresholdKmh": 90,
    "startTime": "2026-06-21T10:15:00Z",
    "endTime": "2026-06-21T10:22:00Z",
    "durationSeconds": 420,
    "exceededByKmh": 20,
    "startLat": "22.543096",
    "startLng": "114.057865",
    "endLat": "22.603096",
    "endLng": "114.117865"
  },
  "fuelImpact": {
    "applicable": true,
    "estimatedExtraFuelLiters": 0.26,
    "confidence": "low_medium",
    "reason": "Estimated from overspeed duration, speed, threshold exceedance, baseline fuel consumption, and configured penalty factors.",
    "estimatedOverspeedDistanceKm": 12.83,
    "baseFuelLiters": 1.28,
    "overspeedRatio": 0.22,
    "overspeedPenaltyRate": 0.2
  },
  "explanation": "The vehicle triggered an overspeed alarm. Extra wasted fuel is estimated from overspeed duration, speed, threshold exceedance, baseline fuel consumption, and configured penalty factors. The result is an estimate for fleet fuel-saving management.",
  "formulaVersion": "fuel-estimated-v1"
}

5.3 Idle Alarm Example

{
  "version": "2026-06-21.v1",
  "eventId": "alarm:123458",
  "eventSequence": 123458,
  "eventType": "business_alarm.created",
  "occurredAt": "2026-06-21T11:20:00Z",
  "pushedAt": "2026-06-21T11:20:05Z",
  "accountId": 10001,
  "imei": "868120000000001",
  "device": {
    "imei": "868120000000001",
    "deviceName": "Vehicle A",
    "licenseNumber": "ABC123",
    "vin": "L1234567890",
    "deviceType": "G19"
  },
  "alarm": {
    "alarmId": 123458,
    "alarmType": "STAY_ACC_ON",
    "alarmCode": 61,
    "alarmName": "STAY_ACC_ON",
    "category": "BUSINESS"
  },
  "source": {
    "type": "device_alarm",
    "table": "device_alarm",
    "id": 123458
  },
  "confidence": "medium",
  "data": {
    "lat": 22.543096,
    "lng": 114.057865,
    "speedKmh": 0,
    "course": 180,
    "locationType": 1,
    "configId": 2002,
    "startTime": "2026-06-21T11:00:00Z",
    "endTime": "2026-06-21T11:20:00Z",
    "durationSeconds": 1200
  },
  "fuelImpact": {
    "applicable": true,
    "estimatedExtraFuelLiters": 0.34,
    "confidence": "medium",
    "reason": "Estimated from ACC-on status, stationary state, chargeable idle duration, and configured idle fuel rate.",
    "durationSeconds": 1200,
    "chargeableDurationSeconds": 1020,
    "idleGraceSeconds": 180,
    "idleFuelLitersPerHour": 1.2
  },
  "explanation": "The vehicle triggered an idle alarm. Idle fuel waste is estimated from ACC-on status, stationary state, chargeable idle duration after the configured grace period, and configured idle fuel rate. The result is an estimate and does not represent measured fuel consumption.",
  "formulaVersion": "fuel-estimated-v1"
}

5.4 Driving Behavior Alarm Example

{
  "version": "2026-06-21.v1",
  "eventId": "alarm:123459",
  "eventSequence": 123459,
  "eventType": "hardware_alarm.created",
  "occurredAt": "2026-06-21T12:05:00Z",
  "pushedAt": "2026-06-21T12:05:03Z",
  "accountId": 10001,
  "imei": "868120000000001",
  "device": {
    "imei": "868120000000001",
    "deviceName": "Vehicle A",
    "licenseNumber": "ABC123",
    "vin": "L1234567890",
    "deviceType": "G19"
  },
  "alarm": {
    "alarmId": 123459,
    "alarmType": "FAST_ACCELERATION",
    "alarmCode": 34,
    "alarmName": "FAST_ACCELERATION",
    "category": "HARDWARE"
  },
  "source": {
    "type": "device_alarm",
    "table": "device_alarm",
    "id": 123459
  },
  "confidence": "medium",
  "data": {
    "lat": 22.543096,
    "lng": 114.057865,
    "speedKmh": 45,
    "course": 180,
    "locationType": 1
  },
  "fuelImpact": {
    "applicable": true,
    "estimatedExtraFuelLiters": 0.03,
    "confidence": "low",
    "reason": "The device reported a harsh acceleration alarm. Fuel impact is estimated per event.",
    "estimatedFuelLitersPerEvent": 0.03,
    "eventCount": 1
  },
  "explanation": "The device reported a driving behavior hardware alarm. Fuel impact is estimated from a configured per-event value. Raw G-sensor/IMU data is not currently available, so the result should be treated as low-confidence management guidance.",
  "formulaVersion": "fuel-estimated-v1"
}

6. Fuel Impact

Fuel impact is an estimate only.

The following fields are estimated values:

estimatedExtraFuelLiters

They are not measured values and should not be treated as actual fuel consumption.

The webhook intentionally does not use field names such as:

actualFuel
realFuel
measuredFuel

6.1 Formula Parameters

Fuel formulas use configurable parameters.

Example configuration:

{
  "version": "fuel-estimated-v1",
  "idleFuelLitersPerHour": 1.2,
  "defaultBaseFuelLitersPer100Km": 10.0,
  "overspeedPenaltyRate": 0.18,
  "overspeedSeverityFactor": 0.5,
  "idleMinSeconds": 300,
  "idleGraceSeconds": 180,
  "longStopMinSeconds": 1800,
  "drivingBehaviorEstimateEnabled": true,
  "harshAccelerationEstimatedFuelLitersPerEvent": 0.03,
  "harshDecelerationEstimatedFuelLitersPerEvent": 0.02,
  "sharpTurnEstimatedFuelLitersPerEvent": 0.015
}

6.2 Idle Fuel Waste Formula

Applies to:

STAY_ACC_ON

Formula:

chargeableDurationSeconds =
  max(0, durationSeconds - idleGraceSeconds)

chargeableIdleHours =
  chargeableDurationSeconds / 3600

estimatedExtraFuelLiters =
  chargeableIdleHours * idleFuelLitersPerHour

Example:

durationSeconds = 1200
idleGraceSeconds = 180
idleFuelLitersPerHour = 1.2

chargeableDurationSeconds = 1200 - 180 = 1020
chargeableIdleHours = 1020 / 3600 = 0.2833
estimatedExtraFuelLiters = 0.2833 * 1.2 = 0.34 L

Confidence:

medium

Reason:

The model uses ACC-on status, stationary state, chargeable idle duration, and configured idle fuel rate. It does not use measured engine fuel flow.

6.3 Overspeed Fuel Waste Formula

Applies to:

SPEED

Formula:

durationHours = durationSeconds / 3600

estimatedOverspeedDistanceKm =
  speedKmh * durationHours

baseFuelLiters =
  estimatedOverspeedDistanceKm * defaultBaseFuelLitersPer100Km / 100

overspeedRatio =
  max(0, speedKmh - speedThresholdKmh) / speedThresholdKmh

effectiveOverspeedPenaltyRate =
  overspeedPenaltyRate * (1 + overspeedSeverityFactor * overspeedRatio)

estimatedExtraFuelLiters =
  baseFuelLiters * effectiveOverspeedPenaltyRate

Example:

speedKmh = 110
speedThresholdKmh = 90
durationSeconds = 420
defaultBaseFuelLitersPer100Km = 10
overspeedPenaltyRate = 0.18
overspeedSeverityFactor = 0.5

durationHours = 420 / 3600 = 0.1167
estimatedOverspeedDistanceKm = 110 * 0.1167 = 12.84 km
baseFuelLiters = 12.84 * 10 / 100 = 1.284 L
overspeedRatio = (110 - 90) / 90 = 0.2222
effectiveOverspeedPenaltyRate = 0.18 * (1 + 0.5 * 0.2222) = 0.20
estimatedExtraFuelLiters = 1.284 * 0.20 = 0.26 L

Confidence:

low_medium

Reason:

The first version estimates overspeed distance from speed and duration, then increases the penalty when the vehicle exceeds the speed threshold by a larger ratio. It does not use measured engine load, road grade, wind, payload weight, or measured fuel flow.

6.4 Long Stop

Applies to:

STAY_TIMEOUT

Current behavior:

Fuel waste estimation is not applied to STAY_TIMEOUT by default.

Reason:

A long stop means the vehicle stayed still for a long period. Without confirmed idle behavior, the system does not estimate fuel waste for this alarm type.

6.5 Harsh Driving

Applies to:

FAST_ACCELERATION
FAST_DECELERATION
SHARP_TURN

Formula:

estimatedExtraFuelLiters =
  configuredFuelLitersPerEvent * eventCount

Default event count:

eventCount = 1

Example:

alarmType = FAST_ACCELERATION
configuredFuelLitersPerEvent = 0.03

estimatedExtraFuelLiters = 0.03 * 1 = 0.03 L

Confidence:

low

Reason:

The event is reported by the device. Raw G-sensor or IMU data is not available in the webhook. Fuel impact is estimated from a configured per-event value and should be treated as management guidance.

7. Unsupported Capabilities

The webhook currently does not provide:

Raw G-sensor data
Raw IMU data
accel_x
accel_y
accel_z
G-force
Crash severity
Measured fuel consumption
Actual fuel consumption
CAN/OBD measured fuel
Payload weight
Engine RPM-based idle validation

If future devices provide validated sensor data, a new formula version can be introduced.

8. Customer Integration Checklist

Before enabling webhook delivery, please confirm:

1. The HTTP or HTTPS endpoint URL.
2. The shared secret used for HMAC signature verification.
3. The subscribed event types.
4. The expected retry behavior.
5. The idle fuel consumption parameter.
6. The baseline fuel consumption parameter.
7. The overspeed penalty rate.
8. The per-event estimated fuel impact for harsh acceleration, harsh deceleration, and sharp turn events.