Skip to content

Cookie preferences

We use cookies for our own analytics, to see how our campaigns perform and, if you allow it, to load content from other services such as the Google site search. We never sell your data. Necessary cookies keep the site working and cannot be switched off. See our Cookie Policy for details and our Privacy Policy for how we handle personal data.

Security, load balancing and remembering your cookie choice.

Show us which pages people read and how they find the site, so we can improve it (Google Analytics).

Show us which of our ad campaigns bring visitors to the site and remember the campaign or partner link you arrived from (Google Ads, partner program). We do not use these cookies to build advertising profiles.

Load the site search from Google when you use it. Google sets its own cookies and shows ads in the search results.
© 2026 The ThingsBoard Authors
2.1k Try for free

ThingsBoard Cloud

Choose your data region

Your data stays in the region you choose, for residency and compliance. No credit card required.

North America Data stored in North America Europe Data stored in the European Union

Rather run it yourself? Install on your own servers

Request

The Request Connector polls external HTTP(S) API endpoints on a configurable schedule, extracts device data from the responses, and forwards it to ThingsBoard as attributes and telemetry. It can also push data to external HTTP(S) APIs in response to shared attribute updates and RPC commands from ThingsBoard.

To enable this connector, add it to the connectors list in tb_gateway.json — see the General Configuration reference.

Connector configuration: request.json

Section titled “Connector configuration: request.json”

The connector reads its settings from a JSON file. Below is a full example with two mapping entries — the first uses a JSON converter, the second uses a custom converter:

{
  "host": "http://127.0.0.1:5000",
  "SSLVerify": true,
  "security": {
    "type": "basic",
    "username": "user",
    "password": "password"
  },
  "mapping": [
    {
      "url": "getdata",
      "httpMethod": "GET",
      "httpHeaders": {
        "ACCEPT": "application/json"
      },
      "allowRedirects": true,
      "timeout": 0.5,
      "scanPeriod": 5,
      "converter": {
        "type": "json",

Section “server”

Section titled “Section “server””
Parameter Default Description
host http://127.0.0.1:5000 Base URL of the external HTTP(S) server
SSLVerify true Verify the server’s SSL certificate

Section “security”

Section titled “Section “security””

Global authorization credentials sent with every request to the external server. Can be overridden per-request in the mapping entries.

The connector sends an Authorization: Basic <base64(username:password)> header with every request.

Parameter Default Description
type basic Authorization type
username username Username
password password Password 
{
  "security": {
    "type": "basic",
    "username": "username",
    "password": "password"
  }
}

Since ThingsBoard IoT Gateway version 3.8.3, environment variables can be specified for username and password fields. This allows you to avoid hardcoding sensitive information in the configuration file and provide it securely at runtime.

To use ENV variables for username and password, you can set them in your environment or define them in your docker-compose.yml file.

The following ENV variables are used for Basic authentication configuration:

  • REQUEST_BASIC_USERNAME
  • REQUEST_BASIC_PASSWORD

Make attention that if you specify ENV variables for username and password, the values from the configuration file will be ignored, and the connector will use the values from the ENV variables instead.

Section “mapping”

Section titled “Section “mapping””

An array of endpoint configurations. Each entry defines a URL to poll, the HTTP method and headers, how often to poll, and how to convert the response into ThingsBoard device data.

Parameter Default Description
url getdata URL path appended to host for the request
httpMethod GET HTTP method (GET, POST, etc.)
httpHeaders {"ACCEPT": "application/json"} Additional HTTP headers
allowRedirects true Follow HTTP redirects
timeout 0.5 Request timeout in seconds
scanPeriod 5 Polling interval in seconds

Subsection “converter”

Section titled “Subsection “converter””

Defines how the HTTP response body is converted into ThingsBoard device data.

The default converter. Parses a JSON response body and maps fields to a device name, type, attributes, and telemetry.

Parameter Default Description
type json Converter type
deviceNameJsonExpression SD8500 JSON expression to extract the device name; a plain string is used as-is
deviceTypeJsonExpression SD JSON expression to extract the device type; a plain string is used as-is
timeout 60000 Milliseconds before a “Device Disconnected” event is triggered
attributes[].type string Data type of the attribute value
attributes[].key serialNumber Attribute key name in ThingsBoard
attributes[].value ${serial} JSON-path expression to extract the value from the response
telemetry[].type string / integer Data type of the telemetry value
telemetry[].key Maintainer Telemetry key name in ThingsBoard
telemetry[].value ${Developer} JSON-path expression to extract the value from the response
telemetry[].tsField (Optional) JSON-path expression for a field carrying a datetime string used as the telemetry timestamp
telemetry[].dayfirst false (Optional) Treat the first number in tsField as the day (true) or month (false)
telemetry[].yearfirst false (Optional) Treat the first number in tsField as the year

Full mapping example:

{
  "url": "getdata",
  "httpMethod": "GET",
  "httpHeaders": {
    "ACCEPT": "application/json"
  },
  "allowRedirects": true,
  "timeout": 0.5,
  "scanPeriod": 5,
  "converter": {
    "type": "json",
    "deviceNameJsonExpression": "SD8500",
    "deviceTypeJsonExpression": "SD",
    "attributes": [
      {
        "key": "serialNumber",
        "type": "string",
        "value": "${serial}"
      }
    ],
    "telemetry": [
      {
        "key": "Maintainer",
        "type": "string",
        "value": "${Developer}"
      },
      {
        "key": "Pressure",
        "type": "integer",
        "value": "${press}",
        "tsField": "${timestampField}",
        "dayfirst": true
      }
    ]
  }
}

You can also combine multiple response fields into a single value using expressions:

{ "key": "combine", "type": "string", "value": "${hum}:${temp}" }

Section “attributeUpdates”

Section titled “Section “attributeUpdates””

Optional. When a ThingsBoard shared attribute changes, the gateway sends an HTTP request to an external URL on the device.

Parameter Default Description
httpMethod GET HTTP method for the outgoing request
httpHeaders {"CONTENT-TYPE": "application/json"} Additional HTTP headers
timeout 0.5 Request timeout in seconds
tries 3 Number of send retries
allowRedirects true Follow HTTP redirects
deviceNameFilter SD.* Regex filter on device name
attributeFilter send_data Regex filter on attribute name
requestUrlExpression sensor/${deviceName}/${attributeKey} Expression to build the target URL
valueExpression {"${attributeKey}":"${attributeValue}"} Expression to build the request body 
"attributeUpdates": [
  {
    "httpMethod": "POST",
    "httpHeaders": {
      "CONTENT-TYPE": "application/json"
    },
    "timeout": 0.5,
    "tries": 3,
    "allowRedirects": true,
    "deviceNameFilter": "SD.*",
    "attributeFilter": "send_data",
    "requestUrlExpression": "sensor/${deviceName}/${attributeKey}",
    "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
  }
]

Section “serverSideRpc”

Section titled “Section “serverSideRpc””

Optional. Maps ThingsBoard RPC commands to outgoing HTTP requests sent to the device.

Parameter Default Description
deviceNameFilter SmartMeter.* Regex filter on device name
methodFilter echo Regex filter on RPC method name
requestUrlExpression sensor/${deviceName}/request/${methodName}/${requestId} Expression to build the target URL
responseTimeout 0.5 Seconds to wait for a response
httpMethod GET HTTP method for the outgoing request
valueExpression ${params} Expression to build the request body
timeout 0.5 Request timeout in seconds
tries 3 Number of send retries
httpHeaders {"CONTENT-TYPE": "application/json"} Additional HTTP headers 
"serverSideRpc": [
  {
    "deviceNameFilter": ".*",
    "methodFilter": "echo",
    "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
    "responseTimeout": 1,
    "httpMethod": "GET",
    "valueExpression": "${params}",
    "timeout": 0.5,
    "tries": 3,
    "httpHeaders": {
      "Content-Type": "application/json"
    }
  },
  {
    "deviceNameFilter": ".*",
    "methodFilter": "no-reply",
    "requestUrlExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
    "httpMethod": "POST",
    "valueExpression": "${params.hum}",
    "httpHeaders": {
      "Content-Type": "application/json"
    }
  }
]

Every telemetry and attribute key also has a built-in GET and SET RPC method available automatically. See the Reserved RPC methods guide for details.

© 2026 The ThingsBoard Authors · Privacy Policy · Cookie Policy ·