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

• Fields

• Reliability

• Batching

• Connection

• Headers

• Framing

• Authentication

• Security

• Health

• Server Output

• Cursors

• Schema

Fields

Field	Type	Required	Description
retry Reliability	Retry		Retry policy for failed sends.
batch Batching	Batch		Logical batching hints.
connect Connection	Connect		Connection strategy for establishing outbound sockets.
url Connection	url (string)		Remote endpoint to publish to (required for client mode). Examples: https://example.com/path
mode Connection	Mode		Operating mode for this output. Allowed values: client, server-output, server-input, relay
headers Headers	map (string)		Headers to include during the WebSocket handshake.
query Headers	map (string)		Query parameters appended to the connection URL.
subprotocols Headers	string[]		Preferred subprotocols.
payload Framing	Payload		Encoding strategy for emitted frames. Allowed values: text, json, binary, binary-base64
auth Authentication	Auth		Authentication material inserted into the handshake.
tls Security	Tls		TLS configuration used when acting as a client.
heartbeat Health	Heartbeat		Optional heartbeat configuration for outgoing connections.
reconnect Reliability	Reconnect		Reconnection policy for client mode.
server Server Output	Server		Embedded server configuration when exposing a WebSocket endpoint.
cursor Cursors	Cursor		Cursor configuration for resume tokens.

Reliability

Show fields

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

Batching

Show fields

Field	Type	Required	Description
batch	Batch		Logical batching hints.

Connection

Show fields

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

Headers

Show fields

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.

Framing

Show fields

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

Authentication

Show fields

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

Security

Show fields

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

Health

Show fields

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

Server Output

Show fields

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

Cursors

Show fields

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

Schema

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

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

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). 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).
wrap-as-json	boolean (bool)		Format the output batch as a JSON array.

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.

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.

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).

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.

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.

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

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.
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.

Headers Table

Header	Value
Header-Name	value

Value format: templated-text.

Query Table

Parameter	Value
param	value

Value format: templated-text.

Auth - Headers Table

Header	Value
Header-Name	value

Value format: templated-text.

Auth - Query Table

Parameter	Value
param	value

Value format: templated-text.

Batch - Mode Options

Value	Description
fixed	Fixed
document	Document

Connect - Mode Options

Value	Description
lazy	Defer connection until the first event needs to be sent.
eager	Establish the connection during initialisation and keep it open.

Mode Options

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

Payload Options

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

Heartbeat - Action Options

Value	Description
reconnect	Reconnect
log-only	Log Only