RealiteQ Webhook Specification

Webhooks, or remote updates, allow you to send updates to your own servers whenever a value changes in your RealiteQ project.

A remote update (webhook) can be generated whenever a value changes on the RealiteQ platform. Remote updates can be configured for each node individually. Remote updates are sent as a webhook (an HTTP request) to the configured URL.

Note: When the given remote update URL uses the http:// scheme, the remote update information is not encrypted, and may be intercepted by malicious actors. It is recommended that you always use the https:// scheme, such that all information is encrypted. Make sure that the receiving server is able to accept encrypted (TLS/SSL) connections.

RealiteQ remote updates work in one of the following modes:

• Unbuffered mode: each value change is sent immediately to the remote server. A separate HTTP request is generated for each value change.

• Buffered mode: value changes are buffered and sent periodically to the remote server. Each HTTP request to the remote server will include all value changes buffered until that point. The sending period can be configured for the project. Periodic webhook requests are made only if one or more value changes have been buffered. A separate buffer will be used for each URL defined for individual nodes.

Configuring remote updates

The remote update mode is configured per-project, using the webhook mode attribute. For buffered remote updates, a buffered webhook interval setting controls the period for sending the remote update requests.

The following attributes can be configured for each node separately:

• remote_update_url: the URL to which remote updates will be sent.

• remote_update_auth: authorization token to be sent with the remote update.

• remote_update_headers: additional HTTP Headers to include in the remote update.

Unbuffered remote updates

Each time a node's state has changed, the Realiteq COMP sends an HTTP POST request to the specified URL, with the following parameters:

• path: the node's path, e.g. /icex1/r1500

• quality: an integer code for the node's quality - 0=unknown, 1=good, 2=bad, 3=invalid, 4=simulated, 5=forced

• stamp: a string representation of the server's local time, in the format %Y-%m-%d %H:%M:%S %z, where the last component is the time zone offset relative to UTC. The time is local to the time zone defined for the project.

• raw_stamp: a unix epoch integer time stamp (UTC)

• local_stamp: a unix epoch integer time stamp offset to the project's local time zone.

• value: a string representation of the current value

• unformatted_value: a string representation of the current value without formatting

• datatype: an integer code for the value's data type: 0=string, 1=integer, 2=floating point, 3=boolean

The parameters are URL encoded and sent as form values (using the content type application/x-www-form-urlencoded). Here is a sample webhook request to http://example.com/realiteq_updates:

POST /realiteq_updates HTTP/1.1
Host: example.com
Content-Length: 133
Content-Type: application/x-www-form-urlencoded

path=%2Ficex1%2Fr1500&quality=1&stamp=2021-04-04%2017:27:40%20+0000&raw_stamp=1281426981&value=0.1m3&unformatted_value=0.1&datatype=2

Buffered remote updates

In buffered mode, a buffer is maintained for each URL. Remote update requests are sent to the different URLs periodically, including all value changes buffered until that point in time. The value changes are sent as a JSON document containing an array, where each entry is a value change including the same fields as for unbuffered mode.

Failed Requests

Failed requests are not retried. The response from the remote HTTP server is logged to the RealiteQ server logs for monitoring and debugging purposes.