Skippr Docs

Appearance

How WebSocket Defines the Raw Data Contract ​

July 2026

For WebSocket, raw data is the live message stream from one endpoint, which means message shape, connection behavior, and required headers are all part of the contract.

Short Answer ​

The raw data contract for WebSocket is the live message stream delivered from one configured ws:// or wss:// endpoint. Skippr opens that connection, optionally sends the configured headers, and ingests the messages it receives, so the raw layer is the upstream message payload and cadence from that specific socket feed.

That is why a WebSocket source should be described as a stream contract rather than a table contract. If wss://stream.example.com/v1 sends product inventory updates every few seconds, raw data is those update messages from that endpoint host. If the service requires an Authorization header for the handshake, that header is part of the source boundary too, because without it the stream you think you are reading does not actually exist.

Why Teams Struggle with This ​

Teams often underestimate how much connection behavior belongs in the data contract for live feeds. A socket source is only usable as raw data when the endpoint, handshake, and message stability are as dependable as the payload schema itself.

  • The configured url decides which stream exists, and changing host or path is a source-contract change, not a minor transport tweak.
  • Required headers belong in the source definition because they determine whether the feed can be opened at all.
  • stream versus batch changes how Skippr consumes the socket, even when the message shape stays the same.
  • If the connection drops repeatedly behind a proxy or firewall, the raw feed is operationally unstable no matter how clean the payload looks.

How Skippr Handles It ​

Skippr keeps WebSocket honest by exposing only the pieces that matter: url, optional headers, and mode. That is useful because engineers can review the actual live-feed boundary instead of burying it inside custom relay code.

The namespace websocket.{url_host} also keeps the source traceable. When downstream teams inspect the raw layer, they can tell which upstream socket host produced the messages they are working with.

  • Connects directly to ws:// or wss:// endpoints.
  • Supports additional request headers for services that require authenticated handshakes.
  • Defaults to stream mode for live message ingestion.
  • Uses the namespace websocket.{url_host} for source lineage.

What the First Useful Version Looks Like ​

The first useful version is one WebSocket URL and one short capture of real messages that the team can inspect together. That proves whether the payload is specific enough to act as a raw source.

If the upstream feed is valuable but unreliable, fix the connection stability before you expand the pipeline. For socket-based sources, availability and record shape are part of the same contract.