Skip to content
LyftData Docs

WebSocket

WebSocket (web-socket)

Section titled “WebSocket (web-socket)”

Consume events from remote WebSocket endpoints.

Messaging Enterprise edition json

Minimal example

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

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 injected during the handshake.

Batching

Section titled “Batching”
Batching
Field Type Required Description
batch Batch Logical batching behaviour shared with other inputs.

Connection

Section titled “Connection”
Connection
Field Type Required Description
url ✓ url (string) ✅ Target WebSocket endpoint (supports templating).
Examples: https://example.com/path
mode Mode Operating mode for the connection (currently client only).
Allowed values: client, server-output, server-input, relay

Cursors

Section titled “Cursors”
Cursors
Field Type Required Description
cursor Cursor Cursor persistence and replay configuration.

Framing

Section titled “Framing”
Framing
Field Type Required Description
permessage-deflate ✓ boolean (bool) Request the permessage-deflate extension during the handshake.
Default: false
payload Payload Interpretation applied to inbound frames.
Default: text
Allowed values: text, json, binary, binary-base64

Headers

Section titled “Headers”
Headers
Field Type Required Description
headers ✓ map (string) Headers applied to the opening handshake (templated).
query ✓ map (string) Query parameters appended to the connection URL.
subprotocols string[] Preferred subprotocols listed in order of precedence.
extract-headers string[] Response headers to surface in event metadata (case-insensitive).

Health

Section titled “Health”
Health
Field Type Required Description
heartbeat Heartbeat Optional heartbeat configuration (ping/pong).

Reliability

Section titled “Reliability”
Reliability
Field Type Required Description
retry Retry Retry configuration applied to user-level failures (message processing, decode).
reconnect Reconnect Reconnection policy applied when the socket closes unexpectedly.

Security

Section titled “Security”
Security
Field Type Required Description
tls Tls TLS configuration for client connections.

Server Input

Section titled “Server Input”
Server Input
Field Type Required Description
server Server Embedded server configuration when operating in server-input mode.

Trigger

Section titled “Trigger”
Trigger
Field Type Required Description
trigger Trigger Optional schedule for reconnect attempts; if omitted runs once and relies on reconnect policy.
Allowed values: message, cron, interval

Schema

Section titled “Schema”

Trigger - Cron - Window - Start Options

Section titled “Trigger - Cron - Window - Start Options”
Option Name Type Description
start-time Start Time object
tracked Tracked string Examples: /path/to/file, c:\users\joe\data\file.txt

Trigger - Interval - Window - Start Options

Section titled “Trigger - Interval - Window - Start Options”
Option Name Type Description
start-time Start Time object
tracked Tracked string Examples: /path/to/file, c:\users\joe\data\file.txt

Trigger Options

Section titled “Trigger Options”
Option Name Type Description
message Message object
cron Cron object
interval Interval object

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
uuid-field field (string) Field where generated uuid, the unique marker for the group, will be stored.
Examples: data_field
invocation-time-field field (string) Field where invocation time will be stored.
Examples: data_field
completion-time-field field (string) Field where completion (end of execution) time will be stored.
Examples: data_field
begin-marker-field field (string) Field used to mark first event in the group.
Examples: data_field
end-marker-field field (string) Field used to mark last event in the group.
Examples: data_field
line-count-field field (string) Field used to store the line count of the batch.
Examples: data_field
line-num-field field (string) Field used to store the line number of the batch.
Examples: data_field

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

Trigger - Message Fields

Section titled “Trigger - Message Fields”
Field Type Required Description
limit ✓ number (integer) The number of times to run the input.
Examples: 42, 1.2e-10
filter-kind Filter Kind Specifies whether the message originated from the “system” or by the “user”.
Allowed values: system, user, runtime-artifact-fetch, runtime-artifact-fetch-error, runtime-artifact-clear, runtime-artifact-clear-ack, runtime-artifact-fetch-reply, runtime-artifact-update, runtime-artifact-update-ack
filter-source Filter Source[] Specifies what process generated the message. Was it a “server”, “worker” or “job”?
Allowed values: job, worker, server
filter-worker string Specifies what worker to select.
filter-job string Specifies the name of the job that the message came from.
filter-type Filter Type[] Specifies that particular types of message ought to match.
Allowed values: worker-licensed, worker-unlicensed, variable, variable-deleted, begin-shutting-down-job, begin-shutting-down-server, begin-shutting-down-worker, broadcast-job-thread-state, broadcast-server-thread-state, broadcast-worker-thread-state, …
filter-tag string Specifies that messages matched ought to carry a tag with a particular value. This only matches against user-generated messages.

Trigger - Cron - Window - Start - Start Time Fields

Section titled “Trigger - Cron - Window - Start - Start Time Fields”
Field Type Required Description
start-time time-format (string) ✅ Allows the windowing to start at a specified time.
Hint: %Y-%m-%d %H:%M:%S%.3f %z
It should in the following format: 2019-07-10 18:45:00.000 +0200
highwatermark-file path (string) ✅ Specify file where timestamp would be stored in order to resume, for when Job has been restarted.
Examples: /path/to/file, c:\users\joe\data\file.txt

Trigger - Cron - Window Fields

Section titled “Trigger - Cron - Window Fields”
Field Type Required Description
size duration (string) ✅ Window size.
offset duration (string) Window offset.
Default: 0s
start Start Specify file where timestamp would be stored in order to resume, for when Job has been restarted.
Allowed values: start-time, tracked

Trigger - Cron Fields

Section titled “Trigger - Cron Fields”
Field Type Required Description
cron cron-expression (string) ✅ The Cron pattern.
immediate ✓ boolean (bool) Run as soon as invoked, instead of waiting for the specified cron interval.
Default: false
random-offset duration (string) Sets a random offset to the schedule, then sticks to it.
Default: 0s
window Window Optional window definition when the schedule should only read a bounded range.

Trigger - Interval - Window - Start - Start Time Fields

Section titled “Trigger - Interval - Window - Start - Start Time Fields”
Field Type Required Description
start-time time-format (string) ✅ Allows the windowing to start at a specified time.
Hint: %Y-%m-%d %H:%M:%S%.3f %z
It should in the following format: 2019-07-10 18:45:00.000 +0200
highwatermark-file path (string) ✅ Specify file where timestamp would be stored in order to resume, for when Job has been restarted.
Examples: /path/to/file, c:\users\joe\data\file.txt

Trigger - Interval - Window Fields

Section titled “Trigger - Interval - Window Fields”
Field Type Required Description
size duration (string) ✅ Window size.
offset duration (string) Window offset.
Default: 0s
start Start Specify file where timestamp would be stored in order to resume, for when Job has been restarted.
Allowed values: start-time, tracked

Trigger - Interval Fields

Section titled “Trigger - Interval Fields”
Field Type Required Description
duration duration (string) ✅ Duration to wait between events.
random-offset duration (string) Sets a random offset to the schedule, then sticks to it.
Default: 0s
window Window Optional window definition when the interval should only cover a bounded range.

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.

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

Trigger - Message - Filter Kind Options

Section titled “Trigger - Message - Filter Kind Options”
Value Aliases Name Description
system system
user user
runtime-artifact-fetch runtime-artifact-fetch
runtime-artifact-fetch-error runtime-artifact-fetch-error
runtime-artifact-clear runtime-artifact-clear
runtime-artifact-clear-ack runtime-artifact-clear-ack
runtime-artifact-fetch-reply runtime-artifact-fetch-reply
runtime-artifact-update runtime-artifact-update
runtime-artifact-update-ack runtime-artifact-update-ack

Trigger - Message - Filter Source Options

Section titled “Trigger - Message - Filter Source Options”
Value Aliases Name Description
job job
worker worker
server server

Trigger - Message - Filter Type Options

Section titled “Trigger - Message - Filter Type Options”
Value Aliases Name Description
worker-licensed worker-licensed
worker-unlicensed worker-unlicensed
variable variable
variable-deleted variable-deleted
begin-shutting-down-job begin-shutting-down-job
begin-shutting-down-server begin-shutting-down-server
begin-shutting-down-worker begin-shutting-down-worker
broadcast-job-thread-state broadcast-job-thread-state
broadcast-server-thread-state broadcast-server-thread-state
broadcast-worker-thread-state broadcast-worker-thread-state
check-job-report-time check-job-report-time
check-worker-report-time check-worker-report-time
de-register-job-thread-dependency de-register-job-thread-dependency
de-register-server-thread-dependency de-register-server-thread-dependency
de-register-worker-thread-dependency de-register-worker-thread-dependency
deployed-job-active deployed-job-active
deployed-job-removed deployed-job-removed
deployed-job-should-be-running deployed-job-should-be-running
deployment-phase deployment-phase
durable-transport-effect-ack durable-transport-effect-ack
heart-beat heart-beat
initialise-internal-state initialise-internal-state
initialise-job-states initialise-job-states
job-batch-end job-batch-end
job-backlog-update job-backlog-update
job-analytics-batch job-analytics-batch
job-checkpoint-update job-checkpoint-update
job-deploy-ready job-deploy-ready
job-deployed job-deployed
job-document-end job-document-end
job-document-start job-document-start
job-errors job-errors
job-execution-anomaly job-execution-anomaly
job-execution-status job-execution-status
job-emit-custom job-emit-custom
job-finished job-finished
job-idle job-idle
job-initiated job-initiated
job-is-processing job-is-processing
job-logs job-logs
job-metrics job-metrics
job-notifications job-notifications
job-removing job-removing
job-removed job-removed
job-remove-failed job-remove-failed
job-remove-ready job-remove-ready
job-replaced job-replaced
job-required job-required
job-run-ended job-run-ended
job-runtime-error job-runtime-error
job-runtime-settings job-runtime-settings
job-run-started job-run-started
job-running-docker job-running-docker
job-running-script job-running-script
job-running-subprocess job-running-subprocess
job-running-system-d job-running-system-d
job-settings job-settings
job-step-statistics job-step-statistics
job-started job-started
job-staged job-staged
job-state-transition job-state-transition
job-shutting-down job-shutting-down
job-stopping job-stopping
job-stopped job-stopped
job-timed-out job-timed-out
job-suspicious-silence job-suspicious-silence
job-thread-state job-thread-state
job-trace job-trace
job-trace-requires-samples job-trace-requires-samples
job-updated job-updated
job-worker-comms-error job-worker-comms-error
job-unstaged job-unstaged
license-state-changed license-state-changed
license-validation-failed license-validation-failed
license-validation-ok license-validation-ok
license-volume-violation license-volume-violation
new-license new-license
override-job-coordinated-shutdown override-job-coordinated-shutdown
override-server-coordinated-shutdown override-server-coordinated-shutdown
override-worker-coordinated-shutdown override-worker-coordinated-shutdown
register-job-thread-dependency register-job-thread-dependency
register-server-thread-dependency register-server-thread-dependency
register-worker-thread-dependency register-worker-thread-dependency
run-job-failure run-job-failure
server-logs server-logs
server-metrics-batch server-metrics-batch
server-started server-started
server-starting server-starting
server-stopping server-stopping
server-thread-state server-thread-state
server-worker-comms-error server-worker-comms-error
shutdown-jobs shutdown-jobs
shutdown-worker shutdown-worker
system-shutdown system-shutdown
update-upstream-sync-for-job update-upstream-sync-for-job
update-upstream-sync-for-worker update-upstream-sync-for-worker
update-variable update-variable
user-alert user-alert
user-generated user-generated
trigger-response trigger-response
trigger-proxy-response trigger-proxy-response
workflow-step-terminal workflow-step-terminal
workflow-step-terminal-ack workflow-step-terminal-ack
user-notification user-notification
worker-command-for-job worker-command-for-job
worker-auth-lease-ack worker-auth-lease-ack
worker-connected worker-connected
worker-created worker-created
worker-debug-heart-beat worker-debug-heart-beat
worker-error worker-error
worker-first-seen worker-first-seen
worker-heart-beat worker-heart-beat
worker-logs worker-logs
worker-metrics-batch worker-metrics-batch
worker-offline worker-offline
worker-requests-auth-lease worker-requests-auth-lease
worker-server-comms-error worker-server-comms-error
worker-settings worker-settings
worker-shutdown worker-shutdown
worker-shutting-down worker-shutting-down
worker-started worker-started
worker-state-uuid worker-state-uuid
worker-stopping worker-stopping
worker-suspicious-silence worker-suspicious-silence
worker-system-information worker-system-information
worker-thread-state worker-thread-state
worker-updated worker-updated
worker-modified worker-modified
worker-removed worker-removed
context-changed context-changed
rerender-deployment rerender-deployment
job-killed job-killed
message-serviced message-serviced
failed-to-service-message failed-to-service-message
worker-wants-initial-settings worker-wants-initial-settings
worker-wants-initial-settings-reply worker-wants-initial-settings-reply
worker-wants-deployed-jobs worker-wants-deployed-jobs
worker-wants-deployed-jobs-reply worker-wants-deployed-jobs-reply
worker-wants-job-configuration worker-wants-job-configuration
worker-wants-job-configuration-reply worker-wants-job-configuration-reply
job-wants-dslir-key job-wants-dslir-key
job-wants-dslir-key-reply job-wants-dslir-key-reply
worker-wants-dslir-key worker-wants-dslir-key
worker-wants-dslir-key-reply worker-wants-dslir-key-reply
job-wants-variables job-wants-variables
job-wants-variables-reply job-wants-variables-reply
job-wants-credentials job-wants-credentials
job-wants-credentials-reply job-wants-credentials-reply
job-wants-credentials-error job-wants-credentials-error
job-wants-secret-variables-reply job-wants-secret-variables-reply
job-credentials-invalidated job-credentials-invalidated
aggregator-health aggregator-health
worker-aggregator-health worker-aggregator-health
worker-verification-token worker-verification-token
worker-requests-verification-token worker-requests-verification-token
runtime-artifact-update runtime-artifact-update
runtime-artifact-update-ack runtime-artifact-update-ack
runtime-artifact-clear runtime-artifact-clear
runtime-artifact-clear-ack runtime-artifact-clear-ack
runtime-artifact-fetch runtime-artifact-fetch
runtime-artifact-fetch-reply runtime-artifact-fetch-reply
runtime-artifact-fetch-error runtime-artifact-fetch-error