Helpful

CallbacksPrinciples

Callback medium

The medium defines the way to forward the event.

EMAIL

You’ll need to set up a valid e-mail, a subject, and the message body.
The subject and the body can contain arbitrary text with defined markup which are the name of variables surrounded by brackets for this callback type.

Body text & variable example: 

Message from device {device} received on {time}


Email medium has to be used for testing and debugging purposes but not to collect data for a commercial solution and large fleet of devices.

HTTP

You’ll need to implement a web-facing service. There are two kinds of callbacks:

SIMPLE

Each message is directly forwarded in a single HTTP request. You can use HTTP GET, POST, or PUT method.

Variables

According to the type of callback, different variables are available. Available variables are detailed per callback type related articles.

The available variables list is displayed above the URL field. These variables can be used in 3 places :


URLas path variables or request parameters
Headersas values of a header. Variables cannot be used in header keys because the format is standardized.
Body

If you choose to use the POST or PUT method, you can define a body template that contains variables. These variables are replaced the same way as in URL or Headers.


Variables example:  

{
    "device":"{device}",
    "data":"{data}",
    "time":{time}
}

Headers

You can set custom headers in your callbacks. For security reasons, we disallow all standards headers except Authorization. This header allows you to use other authentication methods than Basic. You cannot put twice the same header. As you can put your user info in the URL in the form of http://login:password@yourdomain.com, be careful not to put an Authorization header.

GET method

The variables are automatically replaced in the query string.

POST/PUT method

POST or PUT method allows you to set the content-type and the body of your request You can choose the content-type between 3 :


  • application/x-www-form-urlencoded

This is the default content type for POST or PUT requests. When using this content-type, you can set the body in a form-encoded format.

Encoded format example:

device={device}&data={data}&time={time}

If this format is not respected, it will be rejected.

Note that if you put some variables in the query part of the URL, these parameters will be appended to the body, whether it is empty or not. Eg :

POST http://hostname/path?id={device}&time={time}&key1={data}&key2={signal}        

with a body template:     device={device}&data={data}&time={time}       

will result in the following body:       

id={device}&time={time}&key1={data}&key2={signal}&device={device}&data={data}&time={time}

  • application/json

You can set a JSON object in the body :   

{
    "device":"{device}",
    "data":"{data}",
    "time":"{time}"
}

When this content type is chosen, JSON content is validated. If the content does not respect the JSON standard, it will be rejected. Please refer to JSON specification for more details

  • text/plain

This content type is free. No validation is performed (except forbidden characters). Eg :   

the device {device} has received a message

BATCH

Messages are gathered together per callbacks, each line representing a message, then sent in batch using a single HTTP request every second. This avoids a possible peak load that your server can not handle.

As the payload contains multiple messages, only the HTTP POST method is supported. The batch={batch} being a mandatory part of the URL.

When using batch callbacks with the duplicate option (required "Network Metadata" contract option enabled), there is no guarantee that duplicates of a given message will be grouped in the same batch.

It all depends on the exact moment of processing of each of these duplicates.  

POST http://hostname/path?batch={batch}
Give following request:

POST http://hostname/path HTTP1.1
ContentType : application/x-www-form-urlencoded

batch={device};{data};{signal}

{device};{data};{signal}

{device};{data};{signal}

where a line in the body corresponds to a message.

The batch variable could be customizable using the parameter "line pattern"

Can't find what you're looking for ?

Have questions? Our worldwide Community of expert fans can answer them.
Have answers? Join the Community and help!

slack logo

Ask the community >