By Kalshi View Editorial Team · Updated 2026-07-17

Real photo by Rob Wingate / Unsplash, used under the Unsplash License.

Kalshi WebSocket to Webhook Pipeline: Source Checklist

Source-backed answer: Kalshi does not document a native webhook callback registration flow for market updates. The documented real-time path is the WebSocket API. A webhook-style pipeline is therefore a user-operated bridge: authenticate to Kalshi, subscribe to a narrow channel and market set, validate snapshot/delta state, then forward a small normalized event to an allowlisted downstream endpoint.

Inference boundary: “No native webhook registration” means no such workflow was found in the reviewed public documentation. It is not a promise that Kalshi will never add one. Recheck the documentation and changelog before building.

WebSocket and Webhook Are Different Roles

• Kalshi WebSocket: the persistent authenticated upstream connection. The current production URL is wss://external-api-ws.kalshi.com/trade-api/ws/v2.
• Your bridge: validates messages, maintains state, filters events, queues delivery and records observability data.
• Your webhook receiver: a downstream HTTPS endpoint that accepts the bridge's normalized payload. Kalshi does not operate this receiver for the design described here.

1. Authenticate the Handshake Correctly

The WebSocket quick start requires three handshake headers: KALSHI-ACCESS-KEY, KALSHI-ACCESS-SIGNATURE and KALSHI-ACCESS-TIMESTAMP. It documents the signed message as the millisecond timestamp plus GET plus /trade-api/ws/v2. The API-key guide uses RSA-PSS signing.

Keep the private key in server-side secret storage. Do not embed it in browser JavaScript, a mobile app, a public repository, a shared notebook or the webhook payload. Use the demo endpoint, wss://external-api-ws.demo.kalshi.co/trade-api/ws/v2, while validating connection and message handling.

2. Subscribe to the Smallest Useful Stream

For orderbook state, subscribe to orderbook_delta and specify market_ticker or market_tickers. Avoid an unbounded stream when only a few markets matter. Kalshi's quick start also documents ticker, trade, lifecycle, fill and position-related channels; channel access and payloads should be checked in the current reference rather than guessed.

{
  "id": 1,
  "cmd": "subscribe",
  "params": {
    "channels": ["orderbook_delta"],
    "market_tickers": ["REPLACE_WITH_OPEN_MARKET_TICKER"]
  }
}

The placeholder is intentional. Hard-coding a stale example ticker into production monitoring is a common way to build a pipeline that is technically connected but operationally useless.

3. Treat Snapshot and Delta State as a Sequence

The orderbook channel sends orderbook_snapshot first and then incremental orderbook_delta messages. The documented examples include subscription ID sid and sequence seq. Build the state machine fail-closed:

1. Do not forward a derived book until a complete snapshot has been accepted.
2. Record the last seq separately for each subscription.
3. Apply a delta only to the matching subscription and expected sequence.
4. On a gap, duplicate, parse failure or reconnect, mark the state stale.
5. Stop downstream book alerts until a fresh snapshot is obtained.

Kalshi documents update_subscription with a get_snapshot action for the orderbook channel. That gives a supported resnapshot path without pretending a missing delta can be reconstructed.

4. Normalize Before Forwarding

Do not relay the full upstream message blindly. A compact downstream envelope can include a schema version, unique event ID, received timestamp, market ticker, upstream type, subscription ID, sequence, normalized payload and a stale/fresh state flag. Exclude Kalshi credentials and other secrets.

{
  "schema_version": 1,
  "event_id": "sha256-of-stable-fields",
  "received_at": "2026-07-17T16:20:00Z",
  "market_ticker": "...",
  "upstream_type": "orderbook_delta",
  "sid": 2,
  "seq": 103,
  "book_state": "fresh",
  "payload": {"side": "yes", "price_dollars": "0.4200", "delta_fp": "-5.00"}
}

The values are illustrative payload shape, not a live market snapshot. Keep the raw upstream message in an internal append-only log if it is needed for replay or incident analysis.

5. Make Webhook Delivery Idempotent and Bounded

• Allowlist destination hosts; do not accept arbitrary callback URLs from untrusted input.
• Sign outgoing bodies with a separate webhook secret so receivers can verify them.
• Use short connect/read timeouts, exponential backoff with jitter and a maximum attempt count.
• Send through a bounded queue so a slow receiver cannot block the WebSocket reader.
• Use event_id for receiver-side deduplication because retries can deliver twice.
• Place exhausted deliveries in a dead-letter queue and alert on queue age, not only process uptime.

6. Reconnect Without Publishing Stale State

Kalshi's quick start recommends automatic reconnection with exponential backoff and asynchronous message processing. Reconnection is not enough by itself: clear or mark the local book stale, reauthenticate, resubscribe, obtain a new snapshot, and only then resume downstream derived-book alerts.

Track at least connection state, reconnect count, last upstream message time, last accepted sequence, snapshot age, queue depth, delivery attempts, receiver latency and dead-letter count. An “up” process with a stale snapshot is not a healthy market-data service.

7. Keep Market Data Separate From Order Submission

The safer first use is an alert, dashboard or research collector. A correct market-data bridge does not prove that an automated trading system is safe. Order submission introduces account permissions, duplicate-order protection, position limits, loss limits, market status, maintenance pauses and human authorization. Keep the downstream interface read-only until those controls have their own design and tests.

Frequently Asked Questions

Does Kalshi offer native webhook support for market updates?

As reviewed July 17, 2026, Kalshi's public API documentation does not describe a callback-registration endpoint where a user submits a URL for market updates. The documented real-time path is an authenticated WebSocket session. Webhook delivery in this guide is a user-operated bridge downstream of that session.

What authentication does the Kalshi WebSocket API require?

The documented handshake uses KALSHI-ACCESS-KEY, KALSHI-ACCESS-SIGNATURE, and KALSHI-ACCESS-TIMESTAMP headers. The signature covers the timestamp, GET method, and /trade-api/ws/v2 path. Keep the private key in server-side secret storage, not in client-side code.

Does Kalshi WebSocket orderbook data use snapshots or deltas?

The orderbook_delta channel sends an orderbook_snapshot first and then incremental orderbook_delta messages. Snapshot and delta examples contain sid and seq fields. Apply updates only after the snapshot and treat a sequence gap as a reason to stop forwarding derived book state and request or obtain a fresh snapshot.

What is the current Kalshi production WebSocket URL?

Kalshi's WebSocket quick start reviewed July 17, 2026 lists wss://external-api-ws.kalshi.com/trade-api/ws/v2 for production and wss://external-api-ws.demo.kalshi.co/trade-api/ws/v2 for demo. Verify the API environments page before deployment because endpoints can change.

Can I use a Kalshi WebSocket bridge to automate trade execution directly?

A market-data bridge should not be treated as proof that an execution system is safe. Keep alert delivery separate from order submission, use the demo environment, add position and loss limits, and require explicit authorization before connecting any downstream component that can place orders.

Boundary: This is an educational architecture guide, not a hosted service, trading system or guarantee of uninterrupted data. Verify the current Kalshi documentation, test in demo and protect every credential.