HTTP Integration

HTTP Integration converts existing protocols and payload formats to ThingsBoard message format. Common deployment scenarios:

• Stream device or asset data from an external system, IoT platform, or connectivity provider back-end.
• Stream data from a custom cloud application.
• Connect an existing device with a custom HTTP-based protocol to ThingsBoard.

The uplink converter decodes the incoming HTTP request body and maps it to the ThingsBoard data model. The decoder receives:

• payload — raw bytes of the HTTP request body
• metadata — HTTP request headers (as Header:{name} keys, e.g. Header:content-type) and integrationName

It must return deviceName, deviceType, attributes, and telemetry. Both are flat key-value maps — nested objects are not supported. For the full decoder API, see Uplink data converter.

The decoder function used in this tutorial:

/** 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;

/** 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 **/

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}
function decodeToJson(payload) {
   var str = decodeToString(payload);
   var data = JSON.parse(str);
   return data;
}

return result;

The decoder expects a flat JSON body and maps its fields to ThingsBoard:

For request body {"deviceName":"Thermometer A","deviceType":"thermostat","model":"N001","param2":"SN-12345","temperature":25.0} the decoder produces:

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

To adapt this converter to your device:

• Device name from a different field — replace data.deviceName with the field that carries the device identifier in your payload.
• Hardcoded device type — replace data.deviceType with a string literal (e.g. 'thermostat') if all devices share the same profile.
• Rename a field — use outputName: data.sourceField to store the value under a different key in ThingsBoard (as shown with serialNumber: data.param2).
• Different telemetry or attribute fields — add, remove, or rename entries in the telemetry and attributes blocks.
• Non-JSON payload — replace decodeToJson(payload) with decodeToString(payload) and parse the string manually.

Import the uplink converter:

1. Download the uplink converter file:

2. Go to Integrations center ⇾ Data converters.
3. Click + Add data converter ⇾ Import converter.
4. Drag and drop the downloaded JSON file into the Import converter window.
5. Click Import.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to HTTP.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Select existing — choose a previously created HTTP Uplink Converter from the list.
   • Click Next.
4. Downlink data converter:
   • Click Skip — the downlink converter is only required for RPC and can be added later.
5. Connection:
   • Copy the HTTP endpoint URL — you will use it to send uplink messages.
   • In Advanced settings enable Replace response status from ‘No-Content’ to ‘OK’.
   Read more about each parameter in connection settings.
6. Click Add to complete the integration setup.

Go to Integrations center → Integrations (1) and click + Add integration (2). Set Integration type to HTTP (3) and click Next (4) Click Select existing (5), choose HTTP Uplink Converter from the list, and click Next (6) Click Skip (7) on the Downlink data converter step Copy the HTTP endpoint URL (8), expand Advanced settings and enable Replace response status from No-Content to OK (9), then click Add (10)

Base URL

The base address of the ThingsBoard server, used to construct the HTTP endpoint URL.

Example: https://thingsboard.cloud

HTTP endpoint URL

Auto-generated endpoint for this integration. External systems must send HTTP POST requests to this URL.

Format: {baseUrl}/api/v1/integrations/http/{integrationId}

The integrationId is a UUID assigned at creation time, visible in the Connection step of the wizard.

Enable security (Headers filter)

When enabled, ThingsBoard validates each incoming request against a list of required HTTP header name/value pairs. Requests missing any configured header are rejected.

Multiple header filters can be added. All configured headers must be present in every request.

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret. These credentials allow the integration to run as a separate process outside the ThingsBoard cluster — useful when the integration must reach services not accessible from the ThingsBoard server (e.g., in a DMZ or on-premises environment).

Advanced settings

Metadata

Optional key–value pairs attached to the integration. These values are injected into every message processed by the integration and are accessible in converter scripts as integrationMetadata.

Send a test message by running the command below, replacing $YOUR_HTTP_ENDPOINT_URL with the HTTP endpoint URL copied during setup.

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

Go to Entities ⇾ Devices — device Thermometer A is provisioned automatically by the integration. Click it and open the Latest Telemetry tab to confirm temperature = 33.

Go to Integrations center ⇾ Integrations, click HTTP integration, and open the Events tab. You should see one event with status “OK”:

To inspect converter processing, go to Integrations center ⇾ Data converters, click Uplink data converter for HTTP integration, and open its Events tab:

• In shows the raw payload passed to the converter
• Out shows the decoded result (deviceName, deviceType, attributes, telemetry)
• Metadata contains the HTTP request headers and integration name

Events tab of the uplink converter — one Uplink event recorded In: raw JSON payload received by the converter Out: decoded result with deviceName, deviceType, attributes, and telemetry Metadata: HTTP request headers and integration name passed to the converter

Use Dashboards to visualize the received data. ThingsBoard provides Solution Templates with pre-built dashboards for common use cases.

Require a specific HTTP header on every incoming request — requests without it are rejected.

1. Open the HTTP integration, click Toggle edit mode (pencil icon, top right).
2. Enable the Enable security (Headers filter) toggle, enter a header name (e.g. test-header) and value (e.g. secret), click Add, then click Apply changes.

Open the HTTP integration and click Toggle edit mode (pencil button, top right) Enable security, enter a header name and value, click Add, then Apply changes

Once configured, add the required header to every uplink request with -H "$HEADER:$VALUE".

Run the command below, replacing $YOUR_HTTP_ENDPOINT_URL, $HEADER, and $VALUE with your values:

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

Send the uplink message with the security header The header in the curl command (-H "test-header:secret") must match the one configured in the integration

The downlink converter (encoder) transforms a Rule Engine message into the HTTP response body returned to the device. For the full encoder function reference, see Downlink data converter.

HTTP downlinks are not pushed — they are delivered as the response body to the device’s next uplink request. When a downlink is queued, the integration returns 200 OK with the encoded payload instead of 204 No Content.

The encoder function receives msg, metadata, and msgType, and must return an object with:

• contentType — JSON, TEXT, or BINARY (BINARY expects a Base64-encoded string)
• data — the response body string
• metadata — optional key-value pairs

1. Go to Integrations center ⇾ Integrations and open the HTTP Integration.
2. Click Toggle edit mode.
3. In the Downlink data converter field, click Create new.
4. In the Add data converter dialog, enter a name, and write or paste the encoder script.

/** Encoder **/

var result = {
    contentType: "JSON",        // JSON, TEXT, or BINARY (base64)
    data: JSON.stringify(msg),  // encode the full message as the response body
    metadata: {}
};

return result;

/** Encoder **/

var result = {
    contentType: "JSON",        // JSON, TEXT, or BINARY (base64)
    data: JSON.stringify(msg),  // encode the full message as the response body
    metadata: {}
};

return result;

5. Click Add, then click Apply changes.

Open the HTTP integration and click Toggle edit mode (pencil button, top right) Click Create new in the Downlink data converter field Enter a name, paste the encoder script, then click Add Downlink converter assigned — click Apply changes to save

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

1. Go to 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”) and select your HTTP integration. Click Add.
4. Connect the message type switch node to the new integration downlink node using the Attributes Updated link type to trigger downlinks on shared attribute updates, and optionally also using the Post attributes link type to forward attribute post messages as downlinks. Apply changes.

Open the Root Rule Chain and drag the integration downlink node onto the canvas Set the node name, select HTTP integration, then click Add Connect the node to the Attributes Updated / Post attributes output and click Apply changes

When a shared attribute is created or updated, the Rule Engine routes the event to the integration, which queues the encoded payload as the response to the device’s next uplink.

1. Go to Devices, select your device, and navigate to the Attributes tab.
2. Select Shared attributes, click + to add a new attribute.
3. Set the key (e.g. powerState) and value (e.g. on).
4. Click Add.

Send the uplink message again. ThingsBoard returns the downlink payload in the HTTP response:

Re-send the uplink message Response body contains the downlink payload: {"powerState":"on"}

The sent and received data can be viewed in the downlink converter’s Events tab — the In block shows the input data, the Out block shows the encoded message sent to the device, and Metadata shows the request headers:

Events tab of the downlink converter — one Downlink event recorded In: ATTRIBUTES_UPDATED message with msg={powerState:"on"} and metadata Out: encoded payload with contentType JSON and data={"powerState":"on"} Metadata: HTTP request headers passed to the downlink converter

• Integration overview
• Uplink data converter
• Downlink data converter
• Rule Engine
• Remote Integration