WebSocket

WebSocket (web-socket)

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

Messaging json

Minimal example

output:
  web-socket: {}

JSON

{
  "output": {
    "web-socket": {}
  }
}

Contents

• Minimal example

• Authentication

• Batching

• Connection

• Cursors

• Framing

• Headers

• Health

• Reliability

• Security

• Server Output

• Schema

Authentication

Authentication

Field	Type	Required	Description
auth	Auth		Authentication material inserted into the handshake.

Batching

Batching

Field	Type	Required	Description
batch	Batch		Logical batching hints.

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

Cursors

Field	Type	Required	Description
cursor	Cursor		Cursor configuration for resume tokens.

Framing

Framing

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

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

Health

Field	Type	Required	Description
heartbeat	Heartbeat		Optional heartbeat configuration for outgoing connections.

Reliability

Reliability

Field	Type	Required	Description
retry	Retry		Retry policy for failed sends.
reconnect	Reconnect		Reconnection policy for client mode.

Security

Security

Field	Type	Required	Description
tls	Tls		TLS configuration used when acting as a client.

Server Output

Server Output

Field	Type	Required	Description
server	Server		Embedded server configuration when exposing a WebSocket endpoint.

Schema

• Auth - Basic Fields
• Auth Fields
• Batch Fields
• Connect Fields
• Cursor Fields
• Heartbeat Fields
• Retry Fields
• Reconnect Fields
• Tls Fields
• Server - Tls Fields
• Server Fields
• Auth - Headers Table
• Auth - Query Table
• Headers Table
• Query Table
• Batch - Mode Options
• Connect - Mode Options
• Mode Options
• Payload Options
• Heartbeat - Action Options

Auth - Basic Fields

Field	Type	Required	Description
username ✓	string	✅	Username credential (supports templating).
password ✓	string	✅	Password credential (supports templating).

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

Field	Type	Required	Description
fixed-size ✓	number (integer)		maximum number of events in an output batch. 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

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

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

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 Fields

Field	Type	Required	Description
timeout	time-interval (string)	✅	timeout (e.g. 500ms, 2s etc. - default is 30). Examples: 500ms, 2h
retries	number (integer)		number of retries. Examples: 42, 1.2e-10

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

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

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

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

Header	Value
Header-Name	value

Value format: templated-text.

Auth - Query Table

Parameter	Value
param	value

Value format: templated-text.

Headers Table

Header	Value
Header-Name	value

Value format: templated-text.

Query Table

Parameter	Value
param	value

Value format: templated-text.

Batch - Mode Options

Value	Name	Description
fixed	fixed	Fixed
document	document	Document

Connect - Mode Options

Value	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

Value	Name	Description
client	client	Client
server-output	server-output	Server Output
server-input	server-input	Server Input
relay	relay	Relay

Payload Options

Value	Name	Description
text	text	Text
json	json	Json
binary	binary	Binary
binary-base64	binary-base64	Binary Base64

Heartbeat - Action Options

Value	Name	Description
reconnect	reconnect	Reconnect
log-only	log-only	Log Only