Protocol Envelope

Every SmarterLink message is a JSON object with two required top-level fields: a header and a payload.¹

{
  "header": { ... },
  "payload": { ... }
}

Header

Field	Type	Required	Description
payloadType	string	yes	The simple type name of the payload (e.g. "ActiveJobUpdated"). Used by receivers to deserialize the payload into the correct type.
monotonicCounter	integer (int64)	no	A value that increases with each successive message. Can be a timestamp (e.g. .NET ticks since the Unix epoch) or a simple counter. Used to determine relative message order.
protocolRevision	integer	yes	The revision number of the SmarterLink protocol used by this message. Current value: 0.
userData	string	no	Optional free-form string. Passed through transparently by the protocol; interpretation is left to the application.

Payload

The payload object is specific to each event type. All payloads share one common field:

Field	Type	Required	Description
version	integer	yes	The version of this specific payload type's schema. Receivers can use this to handle multiple schema revisions of the same event.

Remaining fields are defined per payload type. See the generated JSON schemas for the full structure of each type.

Example

{
  "header": {
    "payloadType": "ActiveJobUpdated",
    "monotonicCounter": 638765432100000000,
    "protocolRevision": 0,
    "userData": null
  },
  "payload": {
    "version": 1,
    "jobId": "job-2024-001"
  }
}

---

¹ File transfer chunk messages are an exception: raw binary chunk data is transmitted without a JSON envelope. Only the negotiation messages that initiate and acknowledge a transfer use the standard envelope format.

---