Webhook Integration

DataKubo ingests device data via HTTP webhooks. Point your LoRaWAN network server at our ingestion endpoint, and we handle normalization, storage, and device auto-registration.

Endpoint

POST https://api.datakubo.com/api/v1/ingest/water-consumption

Headers

Supported formats

DataKubo detects the format automatically from the payload keys:

Any other payload is rejected with 400 INVALID_PAYLOAD_FORMAT. Extra fields (for example rxInfo, txInfo, rx_metadata) are ignored.

ChirpStack payload

ChirpStack sends an up event when a device transmits data.

{
  "deviceInfo": {
    "tenantName": "your-tenant",
    "deviceName": "Water Meter #1",
    "devEui": "a1b2c3d4e5f60001"
  },
  "time": "2025-08-04T20:34:35.816710+00:00",
  "object": {
    "cumulativeFlowM3": 123.456,
    "batteryVoltage": 3.6,
    "latitude": 40.416775,
    "longitude": -3.70379,
    "altitude": 667.5
  }
}

ChirpStack field mapping

TTN payload

The Things Network sends uplink messages with a decoded_payload field.

{
  "end_device_ids": {
    "dev_eui": "A1B2C3D4E5F60001",
    "application_ids": {
      "application_id": "your-tenant"
    }
  },
  "uplink_message": {
    "decoded_payload": {
      "cumulativeFlowM3": 123.456,
      "battery": 3.6
    }
  },
  "received_at": "2025-08-04T20:34:35.816710+00:00"
}

TTN field mapping

When several consumption or battery fields are present, the first one in the table wins. TTN payloads carry no GPS location; latitude/longitude in a TTN decoder are ignored.

What gets stored

• Consumption is always stored in cubic meters (m³). Send the meter's total reading — the index on its display — not the volume used since the previous uplink. DataKubo works out consumption from the difference between readings.
• New devices are registered automatically on their first uplink. If the tenant name matches a community, the device is linked to it.
• Deleted devices that send data again are reactivated.
• GPS location is read from ChirpStack payloads only.

Hardware alarms

Water meters report their own alarms (burst, leak, etc.). DataKubo reads them as booleans from the ChirpStack object or the TTN decoded_payload — same field names for both:

Send true or false (1/0 and "true"/"false" also work). Any other value — for example a status text like "OK" or a bitmask — is handled differently per format:

• ChirpStack — the value is ignored and the reading is still stored.
• TTN — the whole uplink is rejected with 400 VALIDATION_ERROR. Convert the value to true/false in your payload formatter.

How they're handled:

• Triggered — logged when a flag changes from false to true.
• Cleared — logged when a flag changes back to false, or stops being sent. The meter is the source of truth, so there is no manual acknowledge.
• Alarms are logged even when the device is in maintenance.
• Each event stores the reading and battery level at that moment.

Response codes

Rate limits

Webhook ingestion is rate-limited to 100,000 requests per month per organization. Only successful requests count. The counter resets on the 1st of each month (UTC).

Rate limit headers are included in every ingestion response:

X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 99847
X-RateLimit-Reset: 2025-02-01T00:00:00Z

Next steps

• ChirpStack Guide — step-by-step ChirpStack configuration
• TTN Guide — step-by-step TTN configuration
• LoRaWAN Payload Decoder — check a webhook payload before sending it
• API Reference — all available endpoints