Event types reference
Complete reference for event payloads generated by Blecon Network.
Common envelope
All events use the CloudEvents 1.0 specification:
{
"type": "network.device_spotted",
"source": "blecon",
"specversion": "1.0",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": { }
}
| Field | Type | Description |
|---|---|---|
type |
string | Event type (see sections below) |
source |
string | Always "blecon" |
specversion |
string | Always "1.0" |
id |
string | Unique event identifier (UUID) |
time |
string | ISO 8601 timestamp (UTC) |
datacontenttype |
string | Always "application/json" |
data |
object | Event-specific payload |
Events are delivered in batches — a single webhook POST contains a JSON array of CloudEvent objects.
Spotted event (network.device_spotted)
Generated when a hotspot detects a device.
{
"type": "network.device_spotted",
"source": "blecon",
"specversion": "1.0",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": {
"device_id": "urn:uuid:9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
"network_id": "net_abc123",
"account_id": "acc_def456",
"code": "DEVICE_SPOTTED",
"rssi": -68,
"location": "52.125039,-0.161111",
"location_accuracy_metres": 10.0,
"ap_id": "ap_789012"
}
}
| Data field | Type | Description |
|---|---|---|
device_id |
string | Device identifier (URN format) |
network_id |
string | Network the device belongs to |
account_id |
string | Account ID |
code |
string | Always "DEVICE_SPOTTED" |
ap_id |
string | Hotspot/access point identifier |
hotspot_id |
string | Managed hotspot ID (only if the hotspot is registered to your account) |
rssi |
integer | Signal strength in dBm |
location |
string | Hotspot GPS position as "lat,lon" |
location_accuracy_metres |
float | Hotspot position accuracy |
location_age |
float | Age of hotspot's location data in seconds |
advertising_data |
string | Raw BLE advertising data (hex encoded) |
status_data |
string | Device status data (hex encoded, if present) |
First seen event (network.device_first_seen)
Generated the first time a device is detected after registration. Same payload structure as network.device_spotted.
Position event (network.device_position)
Generated when the positioning engine calculates a device's location.
{
"type": "network.device_position",
"source": "blecon",
"specversion": "1.0",
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": {
"device_id": "urn:uuid:9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
"network_id": "net_abc123",
"account_id": "acc_def456",
"code": "POSITION_UPDATED",
"sample_time": "2026-02-11T15:34:03.000000Z",
"calculated_at": "2026-02-11T15:34:05.123456Z",
"trigger": "movement",
"position": {
"coordinate_system": "local",
"x": 10.5,
"y": 20.3,
"accuracy_meters": 8.0,
"num_hotspots": 1
},
"quality": {
"has_position": true,
"accuracy_tier": "medium",
"confidence": 0.85,
"measurement_duration_seconds": 5.2
},
"geojson": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [0.129528, 52.234794]
},
"properties": {
"device_id": "urn:uuid:9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
"accuracy_meters": 8.0,
"timestamp": "2026-02-11T15:34:05.123456+00:00"
}
},
"zone": {
"zone_id": "zone_abc123",
"zone_name": "Warehouse B",
"confidence": 0.95,
"beacons_detected": 1,
"avg_rssi": -65.3,
"lat": 52.234794,
"lon": 0.129528
}
}
}
| Data field | Type | Description |
|---|---|---|
device_id |
string | Device identifier |
network_id |
string | Network the device belongs to |
account_id |
string | Account ID |
code |
string | Always "POSITION_UPDATED" |
sample_time |
string | When signal measurements were taken |
calculated_at |
string | When the position was calculated |
trigger |
string | Why this update was generated (see below) |
position |
object | Calculated position |
quality |
object | Accuracy metadata |
geojson |
object | GeoJSON Feature with GPS coordinates (when available) |
zone |
object | Zone information (when the device is in a zone) |
Position object
| Field | Type | Description |
|---|---|---|
coordinate_system |
string | "local" or "gps" |
x |
float | X coordinate (local) or longitude (GPS) |
y |
float | Y coordinate (local) or latitude (GPS) |
accuracy_meters |
float | Estimated accuracy in meters |
num_hotspots |
integer | Number of hotspots used in calculation |
Quality object
| Field | Type | Description |
|---|---|---|
has_position |
boolean | Whether a position was calculated |
accuracy_tier |
string | "high", "medium", or "low" |
confidence |
float | Position confidence score (0–1) |
measurement_duration_seconds |
float | Time span of measurements used |
Zone object
| Field | Type | Description |
|---|---|---|
zone_id |
string | Zone identifier |
zone_name |
string | Human-readable zone name |
confidence |
float | Zone assignment confidence |
beacons_detected |
integer | Number of beacons/hotspots detected |
avg_rssi |
float | Average signal strength in the zone |
lat |
float | Zone reference latitude |
lon |
float | Zone reference longitude |
Trigger values
| Value | Description |
|---|---|
movement |
Device moved beyond the movement threshold |
heartbeat |
Periodic update (device stationary) |
zone_change |
Device entered or left a zone |
Device message (device.message.<namespace>.<method>)
Generated when a device sends a one-way message (no response expected). The type field is constructed from the namespace and method — for example, a temperature sensor reading uses device.message.sensor.temperature.
{
"type": "device.message.sensor.temperature",
"source": "blecon",
"specversion": "1.0",
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": {
"device_id": "urn:uuid:9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
"network_id": "net_abc123",
"account_id": "acc_def456",
"text": "Test event from console",
"payload": "1a2b3c4d",
"request_content_type": "application/octet-stream"
}
}
| Data field | Type | Description |
|---|---|---|
device_id |
string | Device identifier |
network_id |
string | Network ID |
account_id |
string | Account ID |
payload |
string | Message payload (hex encoded) |
request_content_type |
string | Content type of the payload |
text |
string | Human-readable message text (if present) |
Device request (device.request.<namespace>.<method>)
Generated when a device sends a two-way request (expecting a response). The event is routed to the first matching route, and the webhook response is forwarded back to the device. Same data fields as device messages.
{
"type": "device.request.config.update",
"source": "blecon",
"specversion": "1.0",
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": {
"device_id": "urn:uuid:9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
"network_id": "net_abc123",
"account_id": "acc_def456",
"payload": "7b22666972...6d776172657d",
"request_content_type": "application/octet-stream"
}
}
Registration events
Device registered (network.device_registered)
{
"type": "network.device_registered",
"source": "blecon",
"specversion": "1.0",
"id": "e5f6a7b8-c9d0-1234-efab-345678901234",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": {
"device_id": "urn:uuid:9f3e2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
"network_id": "net_abc123",
"account_id": "acc_def456"
}
}
Device deregistered (network.device_deregistered)
Same structure as network.device_registered.
Error events
| Event type | Description |
|---|---|
network.request_failed |
Device request failed at protocol level |
network.routing_failed |
No matching route for device request |
device.request_failed |
Device request processing failed |
Webhook delivery format
Webhooks receive events as a JSON array (batch of 1–50 CloudEvent objects):
[
{
"type": "network.device_spotted",
"source": "blecon",
"specversion": "1.0",
"id": "event-1-uuid",
"time": "2026-02-11T15:34:05.123456",
"datacontenttype": "application/json",
"data": { }
},
{
"type": "network.device_spotted",
"source": "blecon",
"specversion": "1.0",
"id": "event-2-uuid",
"time": "2026-02-11T15:34:06.234567",
"datacontenttype": "application/json",
"data": { }
}
]
Your webhook endpoint should return a 200 status code to acknowledge receipt. Failed deliveries are retried with exponential backoff.