How to Configure WebSocket as a Source Connector

May 2026

WebSocket source setup works best when the team treats headers, protocol choice, and long-lived network behavior as part of one integration contract.

Short Answer

Configure WebSocket as a source by setting source.kind to websocket, then providing the url and any required headers. Most public or internal streaming services either need no auth at all or expect a bearer token header such as Authorization, which belongs in an environment variable like WEBSOCKET_AUTH_HEADER rather than hard-coded in the source block.

The clean first setup is one known endpoint, mode: stream, and a decision about whether the service requires ws:// or wss://. If the endpoint is wss://stream.example.com/v1, Skippr should be able to perform the handshake, keep the socket open, and start ingesting messages as long as the runner can maintain outbound connectivity to that host and port.

Why Teams Struggle with This

WebSocket connectors often fail because the service contract is only half-captured. The URL may be right while the auth header is missing, or the endpoint may accept the handshake briefly and then drop the connection because a proxy, firewall, or idle timeout policy sits between the runner and the service.

• The url must use the right protocol, either ws:// or wss://, for the target service.
• Any required headers need to be passed exactly as the service expects.
• The runner has to keep outbound access open to the host and port instead of only reaching them momentarily.
• Long-lived stream connectors need attention to idle timeouts and proxy behavior, not just initial handshake success.

How Skippr Handles It

Skippr keeps WebSocket configuration close to the actual service contract: endpoint URL, request headers, and stream mode. That is useful because the first thing most teams need to validate is whether the runtime can sustain the connection under the same network conditions the production pipeline will face.

When the setup is healthy, the signal is easy to read. Skippr can handshake with the endpoint, keep the connection open, and continuously ingest the messages the upstream service emits without forcing you to bolt on a separate socket client or header-management layer.

• Source config centered on url, optional headers, and connection mode.
• Environment-based header injection for bearer tokens or similar secrets.
• A direct fit for streaming services that publish over WebSocket rather than batch exports.
• Operational behavior that makes network, proxy, and timeout assumptions visible early.

What the First Useful Version Looks Like

Validate the source from the same network segment that will run Skippr so you catch proxy and firewall behavior before the connector becomes a long-lived production stream.

If the service publishes multiple message shapes, document that contract alongside the connector config so downstream schema decisions stay grounded in what the socket actually sends.