Skip to content

WebSocket Event Template

Copy this template to docs/api/websocket/events/<domain>-<event>.md (or extend the domain file under docs/api/websocket/events/) whenever you add or change a WebSocket event. The full contract reference is ../api/websocket/README.md.

# <event.name>

> Direction: `client → server` | `server → client`
> Implementation status: **Implemented** | **Planned**
> Reference: [protocol.md](../protocol.md) · [rooms.md](../rooms.md) ·
> [errors.md](../errors.md) · [rate-limits.md](../rate-limits.md)

## Overview

What the event does, when it fires, and which roles may send/receive it.

## Request (client → server)

```json
{
  "type": "<event.name>",
  "requestId": "req_…",
  "timestamp": "2026-08-03T10:00:00.000Z",
  "data": {}
}
```
Field Type Required Description

Response / acknowledgement

{
  "type": "ack",
  "requestId": "req_…",
  "eventType": "<event.name>",
  "data": {}
}

Server-pushed payload

{
  "type": "<canonical.server.event>",
  "data": {}
}

Errors

Code When

Notes

  • Rooms involved (e.g. auction:<cycleId>).
  • Rate limit: <n>/min (see rate-limits.md).
  • Idempotency / replay semantics.
  • Any mapping between documented and canonical server event names.
---

## Rules

- Keep the envelope fields (`type`, `requestId`, `data`) unchanged.
- Never invent new error codes — reuse [errors.md](../api/websocket/errors.md).
- State the implementation status truthfully (see the status table in
  [../api/websocket/README.md](../api/websocket/README.md)).

## Checklist

- [ ] Direction and roles documented
- [ ] Request/ack/server-push payloads all shown
- [ ] Error codes from the existing list
- [ ] Rate limit stated
- [ ] Implementation status accurate