bleenc v2.24 Events


Events are asynchronous messages generated when Bleenc detects a relevant state change or operation. External applications can use them to update user interfaces, run automations, persist historical data or integrate Bleenc with other systems.

Event delivery methods

Bleenc provides the following delivery methods:

  • MQTT: when the MQTT system interface is enabled, generated events are published to the configured event topic.
  • Event listener polling: create a buffered listener with GET /api/event-listener, then fetch its queued events with GET /api/events/{token}.
  • Server-Sent Events (SSE): connect to GET /api/event-stream to receive events as push notifications over HTTP.
  • Webhooks: configure Bleenc to send matching events as HTTP POST requests to a remote endpoint.
  • Plugins: installed plugins can subscribe to events and implement application-specific processing or forwarding.

Delivery depends on the relevant interface being enabled and on the current license status.

General JSON structure

{
  "id": "tagStateChanged",
  "sequence_number": 6139,
  "timestamp": 1784023200000,
  "data": {
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "current_state": "sleep",
    "previous_state": "active"
  }
}

Event fields

id

The identifier of the event type. All emissions of the same event type use the same value.

sequence_number

A runtime sequence number assigned to each generated event. It increases during the current process lifetime, restarts from 1 when Bleenc starts and wraps after the maximum unsigned 64-bit value.

Consumers should not treat it as a permanent identifier. It is useful for ordering events generated by the same running Bleenc instance.

timestamp

The UTC event creation time, expressed as Unix milliseconds.

data

The event-specific payload. It can contain any JSON value and is omitted when an event has no payload.

The documentation of each event describes the fields exposed inside data.

Polling with an event listener

Create a listener and retain the returned token:

GET /api/event-listener?events=tagStateChanged,tagBatteryLevelChanged&timeout=120

Then poll the listener queue:

GET /api/events/{token}

The response is a JSON array containing the complete event envelopes accumulated since the previous fetch. Polling introduces latency and requires the client to manage token lifetime and fetch frequency.

Receiving events through SSE

Connect an EventSource client to GET /api/event-stream. Use the optional listen query parameter to select event identifiers and project to restrict delivery to events associated with a specific project:

GET /api/event-stream?project=433cb51f-0ae7-49d9-a2d7-fe2d1518d707&listen=tagStateChanged,tagBatteryLevelChanged

Each notification uses event as the SSE event name. Its data field contains the complete Bleenc event envelope. When project is specified, events that are not associated with that project are skipped.

Delivering events with webhooks

A webhook sends matching events to a remote HTTP or HTTPS endpoint. Delivery is asynchronous and uses one in-memory queue and one processing thread for each running webhook.

  1. Implement an HTTP endpoint that accepts POST requests with an application/json body.
  2. Create the webhook with POST /api/webhook. A newly created webhook is disabled and starts in the idle state.
  3. Store the webhook identifier and signature_key securely.
  4. Enable delivery with POST /api/webhook/{id}/enable. The webhook moves through starting to running.
  5. Verify every received signature before processing the event.
  6. Return 200, 202 or 204 promptly after accepting the event.
  7. Disable the webhook before updating or deleting it.

Creation example

{
  "description": "Production tag events",
  "endpoint": "https://example.com/webhooks/bleenc",
  "validate_certificate": true,
  "auth": {
    "mode": "bearer",
    "params": {
      "token": "remote-service-token"
    }
  },
  "project": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "event_selection": "inclusion",
  "events": [
    "tagStateChanged",
    "tagBatteryLevelChanged"
  ],
  "retry_window": 60,
  "retry_interval": 5,
  "signature_key": "replace-with-a-strong-secret"
}

The creation request requires description, endpoint, auth, event_selection, retry_window, retry_interval and signature_key. The project filter and TLS certificate setting are optional.

Event filtering

The event_selection field supports:

Value Behavior
all Delivers every event accepted by the optional project filter
inclusion Delivers only identifiers listed in events
exclusion Delivers every event except identifiers listed in events

When project is configured, the webhook only accepts events implementing IProjectEvent whose project identifier matches. Events that are not associated with a project are skipped.

Remote endpoint authentication

The auth object supports none, basic and bearer. Basic and Bearer modes add the corresponding Authorization header to outgoing requests.

HTTP request sent by Bleenc

Bleenc sends the complete event envelope as the JSON request body. The following headers are added:

Header Description
User-Agent Bleenc version, system identifier and webhook identifier
Authorization Optional Basic or Bearer credentials configured for the webhook
Content-Type Always application/json; charset=utf-8
X-Webhook-Id Webhook identifier
X-Webhook-Event-Id Runtime sequence_number of the delivered event
X-Webhook-Timestamp Delivery-attempt timestamp as Unix seconds
X-Webhook-Signature Hexadecimal HMAC-SHA256 signature

Signature verification

The signature input is composed without additional whitespace:

<timestamp>.<webhook-id>.<raw-request-body>

Bleenc calculates HMAC-SHA256 using signature_key as the secret and sends the hexadecimal digest in X-Webhook-Signature. The receiver must calculate the signature from the exact raw body bytes and compare it using a constant-time comparison.

The receiver should also validate X-Webhook-Timestamp against an acceptable clock window to reduce replay risk.

Delivery results and retries

The following statuses complete delivery successfully: 200, 202 and 204.

Network errors, request timeouts and these response statuses are retried: 408, 425, 429, 500, 502, 503 and 504. Retries wait for retry_interval and continue while the current event remains inside retry_window.

Other non-success statuses are final failures and are not retried. The HTTP request timeout is 30 seconds.

Events are processed sequentially per webhook. Retrying one event delays all later events in that webhook queue. Receivers must be idempotent because a network failure can cause the same event to be delivered more than once.

The pending queue is held in memory. Disabling the webhook or shutting down Bleenc can discard events that have not yet been delivered.

TLS certificate validation

Keep validate_certificate enabled for production HTTPS endpoints. Disabling it allows invalid, expired or self-signed server certificates and should only be used in controlled environments.

Webhook lifecycle APIs

Method and path Operation
GET /api/webhooks List configured webhooks
GET /api/webhook/{id} Get one webhook
POST /api/webhook Create a disabled webhook
PUT /api/webhook/{id} Partially update an idle webhook
POST /api/webhook/{id}/enable Enable an idle webhook
POST /api/webhook/{id}/disable Stop a running or starting webhook
DELETE /api/webhook/{id} Delete an idle webhook

The runtime states are idle, starting, running and stopping. Configuration changes and deletion require the webhook to be idle. Webhooks cannot start while Bleenc is limited by a license error.

Event List

gatewayStatusChanged

A gateway changed its status (online/offline)

Event raised when a Gateway changes its status.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "id": "gw-001",
  "alias": "North gate",
  "online": false,
  "clean": true
}

Data fields description

Field Type Description
project_id string Project identifier
id string Gateway identifier
alias string Gateway alias (Optional)
online bool Boolean identifying whether the gateway is online or offline
clean bool Boolean indicating whether the disconnection from broker was clean or triggered by Last will.

gatewayProjectChanged

A gateway changed its project

Event raised when a gateway Project ID has been changed.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "previous_project_id": "22f39f8e-81fd-4f15-8a87-2fd1a8b6a533",
    "gateway": "gw-001"
}

Data fields description

Field Type Description
project_id string Project identifier
previous_project_id string Previous project identifier
gateway string Gateway identifier

gatewayRemoved

A gateway is removed

Event raised when a gateway is removed from the system.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "id": "gw-001",
    "alias": "North gate"
}

Data fields description

Field Type Description
project_id string Project identifier
id string Gateway identifier
alias string Gateway alias (Optional)

tagCreated

A tag was created

Event raised when a tag is created in the system.

Data payload

The event payload is the serialized tag object returned by Tag.ToJsonObject().

{
  "uid": 8,
  "type": "Tag",
  "model": "bleenc",
  "id": "0a00002f",
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "alias": "Pallet tag 47",
  "last_update": 1747897503525,
  "last_update_et": 3504,
  "location": {
    "type": "static",
    "last_update": 1747897300000,
    "map": {
      "id": "warehouse-floor-1",
      "description": "Warehouse floor 1"
    },
    "zone": {
      "id": "zone-a",
      "description": "Loading bay"
    },
    "position": {
      "x": 12.4,
      "y": 7.8,
      "z": 0
    }
  },
  "device": 10,
  "serial": 47,
  "mac_address": "AA:BB:CC:00:00:2F",
  "network_id": 5908,
  "class": 1,
  "firmware": "1.7.3",
  "hardware": {
    "model": 10,
    "revision": 2,
    "variant": 1,
    "led_0": "rgb",
    "led_1": "monochromatic",
    "led_2": "none",
    "led_3": "none",
    "button_1": true,
    "button_2": true,
    "button_3": false,
    "button_4": false,
    "gpio_1": true,
    "gpio_2": false,
    "gpio_3": false,
    "gpio_4": false,
    "accelerometer": true,
    "buzzer": true,
    "vibration": true,
    "display": false
  },
  "alert_running": false,
  "cfg_seq": 2,
  "cfg_status": "match",
  "cmd_seq": 12,
  "state": "sleep",
  "moving": false,
  "motion_date": 1747845249644,
  "motion_time": 52252471,
  "alert_type": "none",
  "alert_count": 0,
  "button_evt": "none",
  "buttons": [false, false, false, false],
  "button_press_count": 18,
  "power_connected": false,
  "battery_low": false,
  "battery": 2890,
  "calibrated_rssi": -62,
  "receivers": 1,
  "nearest_receiver": {
    "id": "gw-001",
    "alias": "North gate",
    "rssi_raw": -56,
    "rssi": -52.04,
    "rssi_offset": 0,
    "rssi_stability": 0.93,
    "attenuation": -9.96,
    "n": 1,
    "estimated_distance": 0.1,
    "proximity": 4,
    "last_update": 1747897503525,
    "last_update_et": 3504
  },
  "scan_enabled": true,
  "alerts_enabled": true,
  "detected": true
}

Data fields description

Field Type Description
uid number Internal numeric device identifier
type string Device type. For this event the value is Tag
model string Device model. For Bleenc tags the value is bleenc
id string Tag identifier
project_id string Project identifier
alias string Tag alias, if available
last_update number Last tag update timestamp, in Unix milliseconds
last_update_et number Elapsed time from the last update, in milliseconds
location object Static device location, if assigned
from_cache bool Whether the tag was loaded from cache
device number Tag device model number
serial number Tag serial number
mac_address string Tag MAC address, if available
network_id number BLE network identifier
class number Tag class number
firmware string Firmware version, if available
hardware object Hardware information, if available
just_reboot bool Present only when the tag has just rebooted
alert_running bool Whether an alert is currently running on the tag
cfg_seq number Current configuration sequence reported by the tag
cfg_status string Configuration status: none, changed, match or error
cmd_seq number Current command sequence reported by the tag
state string Tag state: cached, default, active, sleep or off
moving bool Whether the tag is currently moving
motion_date number Timestamp of the latest motion state change, in Unix milliseconds
motion_time number Elapsed time spent in the current motion state, in milliseconds
alert_type string Current alert type: none, horizontal, vertical, freefall, shock, mandown, nomotion
alert_count number Number of alerts raised since tag power on
button_evt string Last button event: none, pressed, click_1, click_2, click_3, click_4, click_5, long, multipress
buttons array Buttons involved in the last button event
button_press_count number Button press counter since tag power on
power_connected bool Whether the tag is connected to an external power source
battery_low bool Whether the tag battery is low
restarting bool Present only when the tag is notifying that it is about to restart
battery number Battery level in mV
calibrated_rssi number Calibrated RSSI value
receivers number Number of receivers currently detecting the tag
nearest_receiver object Nearest receiver information, if at least one receiver is available
beaconing object Beaconing configuration, if enabled
scan_enabled bool Present when device scanning is enabled
alerts_enabled bool Present when alerts are enabled
realtime_tracking object Current realtime tracking location, if available
snapshot_tracking object Current snapshot tracking location, if available
detected bool Whether the tag is currently detected by at least one receiver

Nested payloads

buttons

The buttons field is an array of four boolean values. Each index represents whether the corresponding hardware button is active.

[
  true,
  false,
  false,
  false
]

hardware

{
  "model": 10,
  "revision": 2,
  "variant": 1,
  "led_0": "rgb",
  "led_1": "monochromatic",
  "led_2": "none",
  "led_3": "none",
  "button_1": true,
  "button_2": true,
  "button_3": false,
  "button_4": false,
  "gpio_1": true,
  "gpio_2": false,
  "gpio_3": false,
  "gpio_4": false,
  "accelerometer": true,
  "buzzer": true,
  "vibration": true,
  "display": false
}

LED values are none, monochromatic or rgb.

beaconing

Every beaconing object includes:

{
  "type": "ibeacon",
  "channel": "ch37",
  "interval": 1000,
  "tx_power": -8
}

For iBeacon advertising, the object also includes:

{
  "uuid": "fda50693-a4e2-4fb1-afcf-c6eb07647825",
  "major": 1024,
  "minor": 3504
}

For Eddystone advertising, the object also includes:

{
  "namespace_id": "0102030405060708090a",
  "instance_id": "0a00002f0001"
}

nearest_receiver

{
  "id": "gw-001",
  "alias": "North gate",
  "rssi_raw": -56,
  "rssi": -52.04,
  "rssi_offset": 0,
  "rssi_stability": 0.93,
  "attenuation": -9.96,
  "n": 1,
  "estimated_distance": 0.1,
  "proximity": 4,
  "location": {
    "type": "static",
    "last_update": 1747897300000,
    "map": {
      "id": "warehouse-floor-1",
      "description": "Warehouse floor 1"
    },
    "position": {
      "x": 10.1,
      "y": 4.2,
      "z": 3
    }
  },
  "last_update": 1747897503525,
  "last_update_et": 3504
}

The nested location field is the receiver static location and follows the device location payload described below.

location

The location field is a device location object. Static locations and tag tracking locations share these base fields:

{
  "type": "static",
  "last_update": 1747897300000,
  "map": {
    "id": "warehouse-floor-1",
    "description": "Warehouse floor 1"
  }
}

The map object contains:

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "id": "warehouse-floor-1",
  "description": "Warehouse floor 1"
}

Static locations also include a position and may include the zone containing that position:

{
  "type": "static",
  "last_update": 1747897300000,
  "map": {
    "id": "warehouse-floor-1",
    "description": "Warehouse floor 1"
  },
  "zone": {
    "id": "zone-a",
    "description": "Loading bay"
  },
  "position": {
    "x": 12.4,
    "y": 7.8,
    "z": 0
  }
}

Tag tracking locations add a mode field:

{
  "mode": "realtime"
}

realtime_tracking

Realtime tracking locations include the base location fields, mode: "realtime" and an estimator.

Trilateration realtime tracking:

{
  "type": "estimated",
  "last_update": 1747897503525,
  "map": {
    "id": "warehouse-floor-1",
    "description": "Warehouse floor 1"
  },
  "mode": "realtime",
  "estimator": "trilateration",
  "position": {
    "x": 12.4,
    "y": 7.8,
    "z": 0
  },
  "accuracy": 1.2
}

snapshot_tracking

Snapshot tracking locations include the base location fields, mode: "snapshot" and an estimator.

Trilateration snapshot tracking:

{
  "type": "estimated",
  "last_update": 1747897503525,
  "map": {
    "id": "warehouse-floor-1",
    "description": "Warehouse floor 1"
  },
  "mode": "snapshot",
  "estimator": "trilateration",
  "position": {
    "x": 12.4,
    "y": 7.8,
    "z": 0
  },
  "accuracy": 1.2
}

Zoning snapshot tracking with one zone:

{
  "type": "estimated",
  "last_update": 1747897503525,
  "map": {
    "id": "warehouse-floor-1",
    "description": "Warehouse floor 1"
  },
  "mode": "snapshot",
  "estimator": "zoning",
  "zone": {
    "id": "zone-a",
    "description": "Loading bay"
  }
}

Zoning snapshot tracking with multiple zones:

{
  "type": "estimated",
  "last_update": 1747897503525,
  "map": {
    "id": "warehouse-floor-1",
    "description": "Warehouse floor 1"
  },
  "mode": "snapshot",
  "estimator": "zoning",
  "zone": [
    {
      "id": "zone-a",
      "description": "Loading bay"
    },
    {
      "id": "zone-b",
      "description": "Packing area"
    }
  ]
}

position

{
  "x": 12.4,
  "y": 7.8,
  "z": 0
}

zone

A single zone object contains:

{
  "id": "zone-a",
  "description": "Loading bay"
}

When zone is an array, it contains objects with the same shape.

tagProjectChanged

A tag changed its project id

Event raised when a tag Project ID has been changed.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "previous_project_id": "22f39f8e-81fd-4f15-8a87-2fd1a8b6a533",
    "tag": "0a00002f",
    "alias": "Pallet tag 47"
}

Data fields description

Field Type Description
project_id string Project identifier
previous_project_id string Previous project identifier
tag string Tag identifier
alias string Tag alias, if available

tagNetworkChanged

A tag changed its network id

Event raised when a tag network ID has been changed.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "current_network_id": 5908,
  "previous_network_id": 5907
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
current_network_id number Current network ID
previous_network_id number Previous network ID

tagClassChanged

A tag changed its class

Event raised when a tag class has been changed.

Data payload


{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47",
    "current_class": 2,
    "previous_class": 1
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
current_class number Current tag class
previous_class number Previous tag class

tagFirmwareVersionChanged

A tag changed its firmware version

Event raised when the firmware version of a tag has been changed.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47",
    "current_firmware": "1.7.3",
    "previous_firmware": "1.7.2"
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
current_firmware string Current firmware version
previous_firmware string Previous firmware version

tagStateChanged

A tag changes its state

Event raised when a tag changes its current state.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "current_state": "sleep",
  "previous_state": "active"
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
current_state string Current tag state, among:
- cached
- default
- active
- sleep
- off
previous_state string Previous tag state, among:
- cached
- default
- active
- sleep
- off

tagConfigStatusChanged

A tag configuration state changes

Event raised when a tag configuration status is changed

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "current_config_status": "match",
  "previous_config_status": "changed"
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
current_config_status string Current tag configuration status. Possible values are:
-none
- changed
- match
- error
previous_config_status string Previous tag configuration status. Possible values are:
-none
- changed
- match
- error

tagMotionChanged

A tag changed its motion status

Event raised when a the motion status of the tag changes.

Data payload


{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47",
    "moving": true
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
moving bool Boolean reporting wether the tag is moving or not

tagAlertRunning

A tag is currently running an alert

Event raised when an alert is currently running on a tag.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "running": true
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
running bool Boolean identifyng whether an alert is currently running on a tag

tagAlarm

A tag alarm is emitted

Event raised when an alarm is detected on the tag.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "alarm": "shock",
  "counter": 3
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
alarm string Type of alarm depends on the alarm configured on the device:
- none
- horizontal
- vertical
- freefall
- shock
- mandown
- nomotion
counter number Sequential number of alarms raised since tag power on

tagButtonPressCountChanged

A tag button press count is changed

Event raised when a tag button press count changes.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "button_press_count": 18
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
button_press_count number Counter of the button pressures on the device since power on

tagButtonPressed

A tag button is pressed

Event raised when a button is pressed on a tag

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "buttons": [true, false, false, false]
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias (Optional)
buttons array Buttons pressed

tagButtonEvent

A tag button event is emitted

Event raised when a tag button event is emitted

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "button_event": "click_1",
  "buttons": [true, false, false, false]
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
button_event string Type of the button pressed event
buttons array Buttons pressed

Button events

Type Description
none No button pressed
pressed Button pressed
click_1 Single click
click_2 click x 2
click_3 click x 3
click_4 click x 4
click_5 click x 5
long Long press
multipress Multiple button pressed

tagButtonReleased

A tag button is release

Event raised when a tag button is released.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "buttons": [true, false, false, false]
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias (Optional)
buttons array Buttons pressed

tagBatteryLevelChanged

A tag changed its battery level

Event raised when the battery level of a tag changes.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "current_battery_level": 2890,
  "previous_battery_level": 2950
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
current_battery_level number Current battery level in mV
previous_battery_level number Previous battery level in mV

tagPowerConnected

A tag is connected/disconnected to/from powered cable

Event raised when a tag is connected or disconnected from an external power source.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47",
    "connected": false
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
connected bool Boolean identifying whether the tag is currently connected to an external power source

tagLowBattery

A Tag has low battery

Event raised when a tag has low battery.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47",
    "battery": 2420
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
battery number Battery level in mV

tagProximityChanged

A tag changed the proximity value

Event raised when the proximity between a tag and a gateway is changed.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "gateway": "gw-001",
  "current": "near",
  "previous": "far",
  "motion": true
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
gateway string Gateway identifier
current string Current relative proximity between the tag and the gateway. Possible values are:
- none
- far
- near
- immediate
previous string Previous relative proximity between the tag and the gateway. Possible values are:
- none
- far
- near
- immediate
motion bool Whether the Tag is currently moving

tagProximityCheckpointChanged

A tag changed its proximity checkpoint value

Event raised when the proximity checkpoint state between a tag and a gateway changes.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "gateway": "gw-001",
  "current": "on",
  "previous": "off",
  "motion": true
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
gateway string Gateway identifier
current string Current checkpoint state: none, on, or off
previous string Previous checkpoint state: none, on, or off
motion bool Whether the tag is currently moving

When a receiver is removed or expires, the event reports none if its previous state was on or off.

tagDetectionChanged

A tag changed its detection status

Event raised when a tag detection status changes.
A tag is detected if there is at least 1 gateway detecting the tag.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "detected": true
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias (Optional)
detected bool Tag detection state

tagAboutToReboot

A tag is about to reboot

Event raised when a tag receives the command to reboot.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47"
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available

tagReboot

A tag rebooted

Event raised when a tag is rebooted.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47"
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available

tagScan

A tag scan was received

Event raised when a tag scan result is notified. The scan result reports at maximum 3 beacons having the highest normalized RSSI values.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "result": {
    "type": "ibeacon",
    "devices": [
      {
        "major": 1024,
        "minor": 3504,
        "normalized_rssi": 8
      },
      {
        "major": 1024,
        "minor": 3505,
        "normalized_rssi": 0
      },
      {
        "major": 1024,
        "minor": 3500,
        "normalized_rssi": -1
      }
    ]
  }
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
result object Object containing the scan result with scan type (ibeacon/bleenc) and devices' major, minor and normalized RSSI

tagStaticLocationUpdated

A tag changed its static location

Event raised when the static location of the tag has changed.

Data payload

{
    "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
    "tag": "0a00002f",
    "alias": "Pallet tag 47",
    "location": {
        "type": "static",
        "last_update": 1747897300000,
        "map": {
            "id": "warehouse-floor-1",
            "description": "Warehouse floor 1"
        },
        "zone": {
            "id": "zone-a",
            "description": "Loading bay"
        },
        "position": {
            "x": 12.4,
            "y": 7.8,
            "z": 0
        }
    }
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
location object The location assigned to Tag

tagLocationUpdated

A tag changed its location

Event raised when the location of a tag has changed.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47",
  "location": {
    "type": "estimated",
    "last_update": 1747897503525,
    "map": {
      "id": "warehouse-floor-1",
      "description": "Warehouse floor 1"
    },
    "mode": "realtime",
    "estimator": "trilateration",
    "position": {
      "x": 12.4,
      "y": 7.8,
      "z": 0
    },
    "accuracy": 1.2
  }
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available
location object Updated tag location. The payload depends on the location estimation mode.

Location fields

The location object is serialized from the TagLocation instance emitted by the event. It always includes:

Field Type Description
type string Location type. For tag estimations this is estimated.
last_update number Last location update timestamp, in Unix milliseconds.
map object Map information associated with the location.
mode string Location estimation mode: realtime or snapshot.

Realtime locations also include an estimator field. Snapshot and realtime concrete estimators may add extra fields such as position, accuracy or zones.

tagRemoved

A tag was removed

Event raised when a tag is removed from the system.

Data payload

{
  "project_id": "433cb51f-0ae7-49d9-a2d7-fe2d1518d707",
  "tag": "0a00002f",
  "alias": "Pallet tag 47"
}

Data fields description

Field Type Description
project_id string Project identifier
tag string Tag identifier
alias string Tag alias, if available