Helpful

CallbacksPrinciples

Callback medium

The medium defines how an event is forwarded.

EMAIL

You will need to set a valid email address, subject, and message body.
The subject and body can contain plain 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, not to collect data for a production solution and a large fleet of devices.

HTTP

You will 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 callback type, different variables are available. Available variables are detailed per callback type dedicated articles.

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


URLas path variables or request parameters
Headersas header values. 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 set a body template that contains variables. These variables are replaced the same way as in URL or Headers.


Example:  

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

Headers

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

GET method

The variables are automatically replaced in the query string.

POST/PUT method

POST or PUT methods allow setting the content-type and body of your request You can choose the content-type among:


  • 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 complied with, 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}"
}

If 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). E.g.:   

the device {device} has received a message

BATCH

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

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

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

It will depend on the exact moment of processing for each duplicate.  

POST http://hostname/path?batch={batch}
Gives the following result:

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 >