EN Realtime and Webhooks

SSE, WebSockets and webhook documentation

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Event channels separate publishing from subscription permissions. The memory backend serves one process; Redis pub/sub distributes notifications across workers/hosts. Neither is a durable queue or historical event store.

{
  "realtime": {"backend": "memory"},
  "event_channels": [
    {
      "name": "updates", "path": "events/updates",
      "publish_permission": "updates.publish", "subscribe_permission": "updates.subscribe",
      "websocket_enabled": true, "sse_enabled": true,
      "max_message_bytes": 16384, "queue_size": 128,
      "max_websocket_connections": 100, "max_sse_connections": 100,
      "allowed_origins": ["http://localhost:3000"],
      "heartbeat_seconds": 15,
      "websocket_message_requests": 60,
      "websocket_message_window_seconds": 60,
      "websocket_message_burst": 15
    }
  ]
}

Grant the listed permissions to appropriate roles. Default paths use events/<name>; publishing, /stream and /ws routes appear in the actual route map. Use RealtimeSupport and project OpenAPI for message envelopes and response shapes.

Authentication and browser constraints

Query-string API-key options are disabled by default. Native clients can send headers, whereas browser WebSocket/EventSource APIs have different custom-header constraints. Design a secure credential flow around those limitations. Do not embed a long-lived administrator key in a frontend.

Origin allowlists and publish/subscribe permissions are separate. Public subscription does not mean public publishing. Explicitly decide which messages different tenants receive from a shared channel; generic CRUD row filters are not automatically applied to every event payload.

Backpressure and delivery

Slow consumers must not cause unbounded memory growth. Size queues and connection limits for the real message rate. Channel limits can be smaller than the process WebSocket ceiling of 1 MiB. Automatic replay of missed messages after reconnect is not promised.

Clients can resynchronize by fetching current state through HTTP after reconnect. If every event must be processed without loss, use a durable broker/outbox and acknowledgment design.

Proxy and hosting

Use native ASGI and a proxy that forwards WebSocket upgrades. Evaluate buffering and idle timeouts for SSE. Passenger/WSGI's conventional HTTP bridge does not provide persistent WebSocket or Editor call transport.

webhook_docs

This field documents webhook contracts in OpenAPI. It does not implement an outbound dispatcher, retry queue, signing or delivery guarantee. Actual webhook delivery requires suitable hook/worker code and a reliable outbox flow.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• main/framework/events.py
• main/framework/routers/project.py
• main/framework/config.py
• exampleApps/app/RealtimeSupport/config/50-events.json

---

English home · All English pages · Version maintenance