HTTP Integration

HTTP Integration lets devices, gateways, applications, and third-party services send data to ThingsBoard through a dedicated HTTP endpoint. An uplink data converter transforms the incoming request into device or asset data, including telemetry and attributes. ThingsBoard can also return a downlink message in the response to a subsequent HTTP request from the same device.

Use HTTP Integration when:

• A device or gateway sends HTTP(S) requests but cannot use the standard ThingsBoard device APIs.
• A third-party application sends webhooks with a payload format you cannot change.
• A backend or gateway sends custom JSON, text, or binary data that must be converted before ThingsBoard processes it.

1. Receive data. A device or service sends an HTTP request to the integration endpoint.
2. Decode the payload. The uplink converter identifies the device or asset and extracts attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard can create an entity that does not exist yet.
4. Return downlink data (optional). If a downlink is queued for that device, ThingsBoard returns the encoded message in the response to a subsequent uplink request. HTTP Integration does not initiate a separate connection to the device.

• Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• A sample of the request body your device or service sends.

Create the uplink converter, assign it to a new HTTP integration, and send a test request.

The uplink converter reads the HTTP request body and maps it to ThingsBoard entities and data. HTTP Integration uses the Generic converter: you write the decoder in TBEL or JavaScript, or load a ready-made one from the Converters library. For converter types and the full decoder reference, see Uplink data converter.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select HTTP.

4. Name — enter a name, for example HTTP Uplink Converter.

5. Main decoding configuration — the editor is pre-filled with the default decoder template. Use it as a starting point and, if needed, adapt it to your device. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   // Decode an uplink message from a buffer
   // payload - array of bytes
   // metadata - key/value object
   
   /** Decoder **/
   
   // decode payload to JSON
   var data = decodeToJson(payload);
   
   // --- Device name and type ---
   // Take the device name and type from the payload.
   // If deviceType is not provided, it falls back to 'default'.
   var deviceName = data.deviceName != null &&
       data.deviceName.toString().trim() != ''
       ? data.deviceName
   

   ▼Expand

   The template stores the keys listed in attributeKeyList (by default, serialNumber) as attributes and every other payload field, except deviceName, deviceType, ts, and timestamp, as telemetry. To store other keys as attributes, add them to attributeKeyList. If deviceName is missing or empty, the decoder throws an error and the message is not processed. If deviceType is missing or empty, it is set to default.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

The endpoint accepts these request body formats:

Built-in helpers:

For field renaming, nested values, and non-JSON payloads, see Common scripting patterns and the converter examples below.

Test the Decoder

Click Test decoder function below the editor. The dialog opens with pre-filled Metadata rows, Payload content type set to JSON, and this sample payload:

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "serialNumber": "SN-12345",
  "temperature": 25.5
}

Click Test. The Output panel shows:

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "attributes": {
    "serialNumber": "SN-12345"
  },
  "telemetry": {
    "ts": 1793375570587,
    "values": {
      "temperature": 25.5
    }
  }
}

Check that deviceName is set and telemetry.values holds the expected keys. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select HTTP.
   • Name — keep the default HTTP integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose HTTP Uplink Converter.
   • Alternatively, click Create new to write a decoder here, or Library to load a ready-made one.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands to the device.
5. Connection:
   • Copy the HTTP endpoint URL. You need it to send uplinks.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

Send a request to the endpoint, then confirm that ThingsBoard decoded it and created the device.

Replace $YOUR_HTTP_ENDPOINT_URL with the HTTP endpoint URL and run:

curl -v -X POST -d '{"deviceName":"Thermometer A","deviceType":"thermostat","temperature":33}' $YOUR_HTTP_ENDPOINT_URL -H "Content-Type:application/json"

The endpoint returns 204 by default, or 200 if Replace response status from ‘No-Content’ to ‘OK’ is on. HTTP/2 responses (for example, from ThingsBoard Cloud) show only the code (HTTP/2 204). HTTP/1.1 responses add the reason phrase (HTTP/1.1 204 No Content).

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK.
• Converter events — open HTTP Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the received body, Out shows the decoded result, and Metadata shows the request headers and integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created Thermometer A. Open it and confirm temperature = 33 on the Latest telemetry tab.

Anyone who knows the endpoint URL can send data to it. A header filter rejects every request that does not carry the required headers with the exact values, and returns 403 Forbidden before the converter runs.

1. Open the integration and click Toggle edit mode (pencil icon).
2. Turn on Enable security.
3. Under Headers filter, click Add and fill in Header and Value (see the fields below). Repeat for each header. A request must carry all of them.
4. Click Apply changes.

Header filter fields:

Example. Set Header to Authorization and Value to Bearer my-secret-token. Each request then needs this header:

curl -v -X POST \
  -d '{"deviceName":"Thermometer A","deviceType":"thermostat","temperature":33,"model":"SN-001"}' \
  $YOUR_HTTP_ENDPOINT_URL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token"

HTTP downlinks are not pushed. ThingsBoard queues the downlink for the device and returns it as the response body to the next uplink request that the converter maps to that device. That response is always 200 OK.

Use downlink when the device polls for commands or configuration, or when the sender expects data in the response.

The downlink converter turns a Rule Engine message into the response body. For the full encoder reference, see Downlink data converter.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and HTTP integration type are preselected.
3. Enter a name, for example HTTP Downlink Converter.
4. Main encoding configuration opens with the default encoder shown below. Keep it or replace it with your own.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add, then Apply changes.

Default encoder:

/** Encoder **/

// Encode downlink data from the incoming Rule Engine message.
// msg: JSON message payload.
// msgType: message type, e.g. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata: key-value pairs containing additional message data.
// integrationMetadata: key-value pairs configured in the integration.

var result = {
    // Specify the HTTP response body format: JSON, TEXT, or BINARY.
    contentType: "JSON",

    // Serialize the incoming message and use it as the HTTP response body.
    data: JSON.stringify(msg),

    // Add optional metadata when required by the integration.
    metadata: {}
};

return result;

contentType sets the response Content-Type: application/json, text/plain, or application/octet-stream. To add a response header, put it in the encoder’s metadata as Header:<name>.

To send downlinks through the integration, modify the Root Rule Chain:

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. Find the integration downlink node in the node library panel on the left. Drag it onto the canvas.
3. In the node configuration dialog, enter a name (e.g. Downlink to HTTP integration) and select your HTTP integration. Click Add.
4. Connect the message type switch node to the newly created integration downlink node using the Post attributes and Attributes Updated relation types to trigger downlinks whenever shared attributes are created or updated.
5. Apply the changes.

Update a shared attribute to queue a downlink, then send an uplink to receive it.

1. Go to Devices & assets ⇾ Devices, select your device, and open the Attributes tab.
2. Select Shared attributes and click +.
3. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add. ThingsBoard queues the downlink.
4. Send the test uplink again.

• HTTP response — the endpoint returns 200 with the body {"temperatureUploadFrequency":60}.

Re-send the uplink message Response body contains the downlink payload

• Converter events — open the downlink converter’s Events tab. In shows the Rule Engine message, Out shows the encoded response, and Metadata shows the request headers.

Ready-made decoders for common payload shapes. Each example lists the input, the decoder, and the output.

Simple JSON with Explicit Fields

Use when the payload has a few known fields and each one is mapped explicitly.

Input payload:

{
  "deviceName": "Thermometer A",
  "deviceType": "thermostat",
  "model": "SN-001",
  "param2": "SN-12345",
  "temperature": 25.0
}

Decoder:

/** Decoder **/

// Decode JSON body
var data = decodeToJson(payload);

var deviceName = data.deviceName;
var deviceType = data.deviceType;

// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       model: data.model,
       serialNumber: data.param2,  // renamed: param2 → serialNumber
   },
   telemetry: {
       temperature: data.temperature
   }
};

/** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/

return result;

Field mapping:

Output:

{
  "deviceName": "Thermometer A",
  "deviceType": "thermostat",
  "attributes": {
    "model": "SN-001",
    "serialNumber": "SN-12345"
  },
  "telemetry": {
    "temperature": 25.0
  }
}

To adapt:

• Device name in another field — replace data.deviceName with that field.
• One profile for all devices — replace data.deviceType with a string, for example 'thermostat'.
• Rename a field — write outputName: data.sourceField, as with serialNumber: data.param2.
• Non-JSON payload — replace decodeToJson(payload) with decodeToString(payload) and parse the string.

Array of Readings for Multiple Devices

Use when a gateway sends readings from several devices in one request. The decoder returns one object per device, and ThingsBoard creates or updates each device separately.

Input payload:

{
  "gateway": "gw-01",
  "readings": [
    { "device": "node-1", "temp": 21.0, "ts": 1700000001000 },
    { "device": "node-2", "temp": 19.5, "ts": 1700000001000 }
  ]
}

Decoder:

/** Decoder **/

var data   = decodeToJson(payload);
var result = [];

for (var i = 0; i < data.readings.length; i++) {
    var r = data.readings[i];
    result.push({
        deviceName: r.device,
        deviceType: 'node-sensor',
        attributes: {
            gateway:         data.gateway,
            integrationName: metadata['integrationName']
        },
        telemetry: {
            ts:     r.ts,
            values: { temperature: r.temp }
        }
    });
}

/** Helper functions 'decodeToString', 'decodeToJson' and 'toFlatMap' are already built-in **/

return result;

Field mapping:

Output:

[
  {
    "deviceName": "node-1",
    "deviceType": "node-sensor",
    "attributes": {
      "gateway": "gw-01",
      "integrationName": "Test HTTP"
    },
    "telemetry": {
      "ts": 1700000001000,
      "values": { "temperature": 21.0 }
    }
  },
  {
    "deviceName": "node-2",
    "deviceType": "node-sensor",
    "attributes": {
      "gateway": "gw-01",
      "integrationName": "Test HTTP"
    },
    "telemetry": {
      "ts": 1700000001000,
      "values": { "temperature": 19.5 }
    }
  }
]

To adapt:

• Another array name — replace data.readings, for example with data.sensors.
• Another device ID field — replace r.device, for example with r.serialNumber.
• More telemetry — extend values, for example humidity: r.hum.
• Timestamp in seconds — use ts: r.ts * 1000.
• No timestamp — use ts: Date.now().
• Profile per reading — replace 'node-sensor' with r.type.

Nested JSON Flattened with toFlatMap

Use when the payload is deeply nested and every remaining field should become telemetry. toFlatMap produces dot-separated keys (sensors.co2) and skips the keys in excludeKeys.

Input payload:

{
  "deviceName": "air-monitor-X",
  "deviceType": "air-quality",
  "meta": { "source": "cloud", "version": "2.0" },
  "sensors": {
    "co2": 412,
    "pm25": 8.2,
    "voc": 0.3
  },
  "location": {
    "lat": 50.45,
    "lon": 30.52
  },
  "ts": 1700000000000
}

Decoder:

/** Decoder **/

var data = decodeToJson(payload);

// Fields to exclude from telemetry — used as device identity, attributes, or timestamp
var excludeKeys = ['deviceName', 'deviceType', 'ts', 'meta', 'location'];

// Flatten all remaining fields into telemetry (nested objects become dot-separated keys)
var telemetry = {};
telemetry.putAll(toFlatMap(data, excludeKeys, true));

// Use the device timestamp (ms) if present, otherwise the current time
var ts = data.ts != null ? data.ts : Date.now();

var result = {
    deviceName: data.deviceName,
    deviceType: data.deviceType,
    attributes: {
        latitude:        data.location.lat,
        longitude:       data.location.lon,
        source:          data.meta.source,
        integrationName: metadata['integrationName']
    },
    telemetry: {
        ts:     ts,
        values: telemetry
    }
};

/** Helper functions 'decodeToString', 'decodeToJson' and 'toFlatMap' are already built-in **/

return result;

Field mapping:

Output:

{
  "deviceName": "air-monitor-X",
  "deviceType": "air-quality",
  "attributes": {
    "latitude": 50.45,
    "longitude": 30.52,
    "source": "cloud",
    "integrationName": "Test HTTP"
  },
  "telemetry": {
    "ts": 1700000000000,
    "values": {
      "sensors.co2": 412,
      "sensors.pm25": 8.2,
      "sensors.voc": 0.3
    }
  }
}

To adapt:

• Other top-level fields to skip — add them to excludeKeys.
• Rename a flattened key — extract the field explicitly and add its parent to excludeKeys so it is not duplicated.
• More attributes — extract them explicitly, for example firmwareVersion: data.meta.version.
• Timestamp in seconds — use ts: data.ts * 1000.

Delimited Text Payload

Use when the device sends text instead of JSON. decodeToString converts the bytes to a string, and split separates the fields.

Input payload (text/plain):

sensor-001;23.5;60;87

Decoder:

/** Decoder **/

// Decode bytes to a UTF-8 string and split by delimiter
var raw   = decodeToString(payload);
var parts = raw.trim().split(';');

// parts[0] = device name
// parts[1] = temperature
// parts[2] = humidity
// parts[3] = battery

var result = {
    deviceName: parts[0],
    deviceType: 'csv-sensor',
    attributes: {
        integrationName: metadata['integrationName']
    },
    telemetry: {
        ts: Date.now(),
        values: {
            temperature: parseFloat(parts[1]),
            humidity:    parseFloat(parts[2]),
            battery:     parseInt(parts[3])
        }
    }
};

/** Helper functions 'decodeToString', 'decodeToJson' and 'toFlatMap' are already built-in **/

return result;

Field mapping:

Output:

{
  "deviceName": "sensor-001",
  "deviceType": "csv-sensor",
  "attributes": {
    "integrationName": "Test HTTP"
  },
  "telemetry": {
    "ts": 1780299924174,
    "values": {
      "temperature": 23.5,
      "humidity": 60.0,
      "battery": 87
    }
  }
}

To adapt:

• Another delimiter — replace ';', for example with ',' or '|'.
• Device name not in the payload — use a fixed string or a metadata value instead of parts[0].
• Another field order — change the indexes.
• Timestamp in the string — parse it, for example ts: parseInt(parts[4]), and convert seconds to milliseconds.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• Rule Engine — how messages are processed after decoding.