ReportPlaneDocs
WebsiteOpen console

WebSocket ingest

Stream text JSON messages over one authenticated connection and process per-message acknowledgements.

Last verified 2026-08-02

WebSocket ingest keeps a connection open and accepts a sequence of text JSON messages. Use the endpoint shown by the ingest client because the runtime path is configuration-driven.

Connect

Provide authentication during the HTTP upgrade request. The connection inherits the source IP, credential, mTLS certificate, and user-agent context used by runtime policy.

The server enforces total and per-source connection limits. A connection can be rejected with HTTP 429 when those limits are full.

Send a message

Each text message uses the same envelope as HTTP JSON ingest:

{
  "schema": "page_view",
  "data": [
    {
      "occurred_at": "2026-08-02T12:00:00Z",
      "account_id": "acct_123",
      "path": "/dashboard"
    }
  ]
}

Binary messages are not supported. Oversized messages are rejected according to the runtime message limit.

Acknowledgement

Every successfully processed message receives JSON like:

{
  "type": "ack",
  "status": "accepted",
  "ingest_id": "ing_...",
  "accepted": 1
}

A message-level failure returns an error frame instead of closing a healthy connection immediately:

{
  "type": "error",
  "message": "schema is not allowed"
}

Connection health

The server sends ping frames on a configured interval and closes connections that do not answer within the pong timeout. Clients must implement normal WebSocket ping/pong behavior and reconnect with bounded backoff.

Delivery guarantees

An acknowledgement means the message entered the accepted delivery path. As with HTTP, warehouse dispatch is asynchronous. Keep application-level message IDs in your data model if your domain needs independent deduplication or traceability.

Was this page helpful?Send feedback