Skip to content
LyftData Docs

WebSocket

WebSocket (web-socket)

Section titled “WebSocket (web-socket)”

Send events to remote WebSocket peers or expose an embedded server.

Messaging Enterprise edition json

Minimal example

Section titled “Minimal example”
output:
  web-socket: {}
JSON 
{
  "output": {
    "web-socket": {}
  }
}

Contents

Section titled “Contents”

A ✓ marks a field that accepts a context variable such as {{ VARIABLE }}.

Authentication

Section titled “Authentication”
Authentication
Field Type Required Description
auth Auth Authentication material inserted into the handshake.

Batching

Section titled “Batching”
Batching
Field Type Required Description
batch Batch Logical batching hints.

Connection

Section titled “Connection”
Connection
Field Type Required Description
connect Connect Connection strategy for establishing outbound sockets.
url ✓ url (string) Remote endpoint to publish to (required for client mode).
Examples: https://example.com/path
mode Mode Operating mode for this output.
Allowed values: client, server-output, server-input, relay

Cursors

Section titled “Cursors”
Cursors
Field Type Required Description
cursor Cursor Cursor configuration for resume tokens.

Framing

Section titled “Framing”
Framing
Field Type Required Description
payload Payload Encoding strategy for emitted frames.
Default: text
Allowed values: text, json, binary, binary-base64

Headers

Section titled “Headers”
Headers
Field Type Required Description
headers ✓ map (string) Headers to include during the WebSocket handshake.
query ✓ map (string) Query parameters appended to the connection URL.
subprotocols string[] Preferred subprotocols.

Health

Section titled “Health”
Health
Field Type Required Description
heartbeat Heartbeat Optional heartbeat configuration for outgoing connections.

Reliability

Section titled “Reliability”
Reliability
Field Type Required Description
retry Retry Retry policy for failed sends.
reconnect Reconnect Reconnection policy for client mode.

Security

Section titled “Security”
Security
Field Type Required Description
tls Tls TLS configuration used when acting as a client.

Server Output

Section titled “Server Output”
Server Output
Field Type Required Description
server Server Embedded server configuration when exposing a WebSocket endpoint.

Schema

Section titled “Schema”

Auth - Basic Fields

Section titled “Auth - Basic Fields”
Field Type Required Description
username ✓ string ✅ Username credential (supports templating).
password ✓ string ✅ Password credential (supports templating).

Auth Fields

Section titled “Auth Fields”
Field Type Required Description
headers ✓ map (string) Static or templated headers added during the handshake.
query ✓ map (string) Query parameters added to the connection URL.
bearer-token ✓ string Bearer token inserted as Authorization: Bearer ....
basic Basic Basic auth credentials sent via header.

Batch Fields

Section titled “Batch Fields”
Field Type Required Description
fixed-size ✓ number (integer) maximum number of events in an output batch.
Examples: 42, 1.2e-10
max-bytes ✓ number (integer) Close the batch before adding an event that would make the serialized request payload exceed this many bytes.
Examples: 42, 1.2e-10
mode Mode ✅ If ‘document’ send on end of document generated by input. If ‘fixed’, use fixed_size.
Allowed values: fixed, document
timeout time-interval (string) ✅ interval after which the batch is sent, to keep throughput going (default 100ms).
Default: 100ms
Examples: 500ms, 2h
header multiline-text (string) put a header line before the batch.
footer multiline-text (string) put a header line after the last line of the batch.
use-document-marker ✓ boolean (bool) Enrich the job metadata with a document marker (for document handling in batch mode).
Default: false
wrap-as-json ✓ boolean (bool) Format the output batch as a JSON array.
Default: false

Connect Fields

Section titled “Connect Fields”
Field Type Required Description
mode Mode Specifies whether to connect eagerly during startup or lazily on demand.
Allowed values: lazy, eager
eager-timeout ✓ string Optional timeout to wait for an eager connection before failing start-up.

Cursor Fields

Section titled “Cursor Fields”
Field Type Required Description
header-name string Header name used to propagate the cursor on reconnect (e.g. Last-Event-ID).
query-parameter string Query parameter name used to propagate the cursor value.
persist-to string Storage location for cursor state (defaults to job-scoped state).
initial-value ✓ string Initial cursor value to send on the first connection.
state-id string Optional explicit state identifier when sharing cursors across jobs.
resume-on-reconnect ✓ boolean (bool) Whether to inject the cursor on every reconnect attempt.
Default: false
value-field field (string) Event field used to derive the cursor value after successful delivery.
Examples: data_field
value-pointer json-pointer (string) JSON pointer used to derive the cursor value from emitted payloads.

Heartbeat Fields

Section titled “Heartbeat Fields”
Field Type Required Description
ping-interval ✓ string Interval between ping frames.
timeout ✓ string Grace period for receiving a pong before the connection is considered unhealthy.
action Action What to do when a heartbeat misses the timeout.
Allowed values: reconnect, log-only
payload ✓ string Optional ping payload to send with heartbeats.

Retry - Backoff Fields

Section titled “Retry - Backoff Fields”
Field Type Required Description
strategy Strategy Backoff strategy to use (default exponential).
Allowed values: exponential, linear, fixed
base string Base delay before retrying (e.g. “200ms”).
max string Maximum delay between retries.
jitter ✓ boolean (bool) Whether to add jitter to retry delays.
Default: false

Retry Fields

Section titled “Retry Fields”
Field Type Required Description
max-attempts number (integer) Maximum attempts before giving up.
Examples: 42, 1.2e-10
forever ✓ boolean (bool) Retry indefinitely until cancelled.
Default: false
backoff Backoff Backoff strategy configuration.

Reconnect Fields

Section titled “Reconnect Fields”
Field Type Required Description
initial-backoff ✓ string Backoff applied after the first failure (human-friendly duration).
max-backoff ✓ string Maximum backoff duration before clamping (human-friendly duration).
multiplier number (integer) Exponential multiplier applied after each failure.
Examples: 42, 1.2e-10
jitter number (integer) Random jitter factor applied to backoff windows (0.0-1.0).
Examples: 42, 1.2e-10
max-attempts number (integer) Maximum number of consecutive attempts before giving up (None=infinite).
Examples: 42, 1.2e-10
reset-after ✓ string Time after a successful connection before resetting the attempt counter.

Tls Fields

Section titled “Tls Fields”
Field Type Required Description
ca-certificate ✓ string Custom CA certificate to trust.
client-certificate ✓ string Client certificate for mutual TLS.
client-key ✓ string Client private key for mutual TLS.
insecure-skip-verify ✓ boolean (bool) Skip certificate validation (unsafe).
Default: false

Server - Tls Fields

Section titled “Server - Tls Fields”
Field Type Required Description
cert path (string) ✅ Path to the certificate file.
Examples: /path/to/file, c:\users\joe\data\file.txt
key path (string) ✅ Path to the private key file.
Examples: /path/to/file, c:\users\joe\data\file.txt

Server Fields

Section titled “Server Fields”
Field Type Required Description
bind string ✅ Address to bind (e.g. 0.0.0.0:8080).
path string Optional path/route restriction.
tls Tls Optional TLS material for the listener.
max-connections number (integer) Maximum simultaneously connected clients (None = unlimited).
Examples: 42, 1.2e-10
idle-timeout ✓ string Disconnect clients after this idle duration.
allowed-origins string[] Restrict accepted requests to these Origin / Sec-WebSocket-Origin values.
send-buffer-capacity number (integer) Per-connection send buffer (messages queued when clients are slow).
Examples: 42, 1.2e-10

Auth - Headers Table

Section titled “Auth - Headers Table”
Header Value
Header-Name value

Value format: templated-text.

Auth - Query Table

Section titled “Auth - Query Table”
Parameter Value
param value

Value format: templated-text.

Headers Table

Section titled “Headers Table”
Header Value
Header-Name value

Value format: templated-text.

Query Table

Section titled “Query Table”
Parameter Value
param value

Value format: templated-text.

Batch - Mode Options

Section titled “Batch - Mode Options”
Value Aliases Name Description
fixed fixed
document document

Connect - Mode Options

Section titled “Connect - Mode Options”
Value Aliases Name Description
lazy lazy Defer connection until the first event needs to be sent.
eager eager Establish the connection during initialisation and keep it open.

Mode Options

Section titled “Mode Options”
Value Aliases Name Description
client client
server-output server-output
server-input server-input
relay relay

Payload Options

Section titled “Payload Options”
Value Aliases Name Description
text text
json json
binary binary
binary-base64 binary-base64

Heartbeat - Action Options

Section titled “Heartbeat - Action Options”
Value Aliases Name Description
reconnect reconnect
log-only log-only

Retry - Backoff - Strategy Options

Section titled “Retry - Backoff - Strategy Options”
Value Aliases Name Description
exponential exponential
linear linear
fixed fixed