This page contains detailed information about the HTTP service in the Tartabit IoT Bridge. This service allows you to send and receive HTTP(S) requests for easy integration with other systems and services.
POST
, GET
, PUT
, OPTIONS
GET
, POST
, PUT
If you have a remote HTTP(S) client that needs to make calls into the IoT Bridge, then you will be using the HTTP server. You can target your service by making calls to https:///webhook/. No other authorization is required, but you can implement your own additional security by inspecting the Authorization header if it is provided.
You can configure the HTTP Service
to extract an endpoint key from the incoming request and link the request to an endpoint. If the endpoint doesn't exist, it will be automatically created. This is most useful if the HTTP requests are related to IoT devices.
Below you will find a sample request:
{
"headers": {
"X-Real-Ip": [
"18.196.213.123"
],
"DeviceId":"31012405106124"
},
"path": "/1bn94uesZp7tQQ955CclcvK6VBXzheEn/31012405106124/e.aspx",
"pathSegments": [
"1bn94uesZp7tQQ955CclcvK6VBXzheEn",
"31012405106124",
"e.aspx"
],
"query": {
"did": "31012405106124",
},
"body": {
"deviceId": "31012405106124",
"temp": 35.2
}
}
body
header
path-segment
query
Somtimes endpoint keys are encoded in the payloads and must be decoded before they can be used. There are several decoders that can be used by adding a vertical bar '|' and the decoder name to the endpoint key field:
The value will be base64 decoded, then re-encoded as hex, useful for binary key values that are standardized on hex formatting.
The value will be base64 decoded and used as a string.
The value will be hex decoded and used as a string.
You might get a request like this:
{
...
"path": "/1bn94uesZp7tQQ955CclcvK6VBXzheEn",
...
"body": {
"deviceId": "MzEwMTI0MDUxMDYxMjQ=",
"temp": 35.2
}
}
If your key were to come in base64 encoded as 'MzEwMTI0MDUxMDYxMjQ=' in the request, but you want to use the decoded value as your endpoint key, you can specify the Endpoint key field as deviceId|b64
to decode the value to '31012405106124'.
You may wish to validate endpoint keys to ensure they are correct. For this, you can use regular expressions to validate the endpoint key that was parsed using the decoder. Regular expressions follow Google's RE2 format (https://github.com/google/re2/wiki/Syntax).
Below are some examples of the regular expressions:
^\d{15,16}$
One of the most important aspects of the HTTPS server is returning data back to the client. This is done using the trigger.reply()
function to indicate how you want the server to reply to the client.
Here are some examples of how to use the trigger.reply()
function:
// return a simple 200 to the client
trigger.reply({status: 200})
// return a simple JSON document, and set the content type:
trigger.reply({ status: 200, headers: {'Content-Type':'application/json'}, body: { myjson: 'abc123'})
// return binary data to the client
trigger.reply({status: 200, body: [0x01, 0x02, 0x03]})
// return an error to the client
trigger.reply({status:500, body: 'error processing request'})
The HTTP Connector is used by both the HTTP client actions and server events. For servers, the service contains the webhook secret used to authenticate and route the incoming HTTP request. For clients, the service is used an an anchor for metering and additional functionality will be added in the future.
body
, header
, path-segment
, or query
.event.data.headers.key1[0]
notation.event.data.pathSegments[1]
will refer to the first path segment after the webhook key.This event fires when an HTTP POST is received by the server.
{
"body":{
"key1":"abc",
"key2":456
},
"headers":{
"key1": ["abc"],
"key2": [456]
}
"path":"/asdf923r0v01v03/data",
"pathSegments": [ "asdf923r0v01v03", "data" ],
"query": {
"arg1":"abc"
}
}
This event fires when an HTTP PUT is received by the server.
{
"body":{
"key1":"abc",
"key2":456
},
"headers":{
"key1": ["abc"],
"key2": [456]
}
"path":"/asdf923r0v01v03/data",
"pathSegments": [ "asdf923r0v01v03", "data" ],
"query": {
"arg1":"abc"
}
}
This event fires when an HTTP GET is received by the server, it is the same as POST/PUT but there will never be a body.
{
"headers":{
"key1": ["abc"],
"key2": [456]
}
"path":"/asdf923r0v01v03/data",
"pathSegments": [ "asdf923r0v01v03", "data" ],
"query": {
"arg1":"abc"
}
}
var options = {
headers: { Authorization: 'BEARER <mytoken>' }
}
Issue an HTTP GET request on the target URL.
// Issue a GET request on www.google.com.
http.get('myhttpservice','https://www.google.com')
// Issue a GET request on www.google.com with a bearer Authorization token.
http.get('myhttpservice','https://www.google.com', {headers: {Authorization: 'BEARER tokeb'}})
Issue an HTTP POST request on the target URL.
// Issue a POST request on www.google.com with a JSON payload.
http.post('myhttpservice','https://www.google.com', {abc: 123, def: '456'})
Issue an HTTP PUT request on the target URL.
// Issue a PUT request on www.google.com with a JSON payload.
http.put('myhttpservice','https://www.google.com', {abc: 123, def: '456'})
The following events are considered billable:
While you can modify the webhook secret, keep in mind that it is a secret, and choosing a secret that is not cryptographically secure can result in unauthorized use of your account.