Skip to main content
Authenticated API

WebSocket connections require a valid JWT Bearer token. Connect via the API gateway at /v1/ws.

WebSocket Events

Reference for all real-time events.

Overview​

Events are organized by channel:

ChannelEventsDescription
ordersOrder lifecycle eventsOrder created, updated, completed
kdsKitchen display eventsTickets, bumps, alerts
inventoryStock eventsLow stock, received
analyticsMetrics updatesReal-time KPIs
tablesTable statusSeated, cleared
notificationsUser notificationsAlerts, messages

Event Format​

All events follow this structure:

{
  "type": "event",
  "channel": "orders",
  "event": "order.created",
  "data": {
    ...event payload
  },
  "timestamp": "2026-01-18T14:30:00Z",
  "location_id": "loc-xyz789"
}

Order Events​

order.created​

New order created.

{
  "event": "order.created",
  "data": {
    "id": "order-12345",
    "number": "1234",
    "type": "dine_in",
    "status": "open",
    "table": "Table 7",
    "server": "Sarah",
    "items": [
      {
        "id": "line-001",
        "name": "Classic Burger",
        "quantity": 2,
        "price": 25.98
      }
    ],
    "subtotal": 25.98,
    "created_at": "2026-01-18T14:30:00Z"
  }
}

order.updated​

Order modified.

{
  "event": "order.updated",
  "data": {
    "id": "order-12345",
    "changes": ["items_added", "subtotal_changed"],
    "items_added": [
      {
        "id": "line-002",
        "name": "Fries",
        "quantity": 2,
        "price": 9.98
      }
    ],
    "subtotal": 35.96,
    "updated_at": "2026-01-18T14:32:00Z"
  }
}

order.sent_to_kitchen​

Order sent to kitchen.

{
  "event": "order.sent_to_kitchen",
  "data": {
    "id": "order-12345",
    "tickets_created": ["ticket-001", "ticket-002"],
    "sent_at": "2026-01-18T14:32:30Z"
  }
}

order.status_changed​

Order status updated.

{
  "event": "order.status_changed",
  "data": {
    "id": "order-12345",
    "previous_status": "preparing",
    "status": "ready",
    "changed_at": "2026-01-18T14:45:00Z"
  }
}

order.paid​

Payment completed.

{
  "event": "order.paid",
  "data": {
    "id": "order-12345",
    "payment": {
      "id": "payment-001",
      "method": "card",
      "amount": 42.50,
      "tip": 6.50,
      "total": 49.00
    },
    "paid_at": "2026-01-18T15:00:00Z"
  }
}

order.closed​

Order completed.

{
  "event": "order.closed",
  "data": {
    "id": "order-12345",
    "total": 49.00,
    "duration_minutes": 45,
    "closed_at": "2026-01-18T15:15:00Z"
  }
}

KDS Events​

kds.ticket.created​

New kitchen ticket.

{
  "event": "kds.ticket.created",
  "data": {
    "id": "ticket-001",
    "order_id": "order-12345",
    "order_number": "1234",
    "station": "grill",
    "items": [
      {
        "name": "Classic Burger",
        "quantity": 2,
        "modifiers": ["Medium", "No Onions"],
        "seat": 1
      }
    ],
    "priority": "normal",
    "created_at": "2026-01-18T14:32:30Z"
  }
}

kds.ticket.bumped​

Ticket marked complete.

{
  "event": "kds.ticket.bumped",
  "data": {
    "id": "ticket-001",
    "order_id": "order-12345",
    "station": "grill",
    "next_station": "expo",
    "prep_time_seconds": 420,
    "bumped_by": "user-chef01",
    "bumped_at": "2026-01-18T14:39:30Z"
  }
}

kds.ticket.late​

Ticket exceeded target time.

{
  "event": "kds.ticket.late",
  "data": {
    "id": "ticket-001",
    "order_id": "order-12345",
    "station": "grill",
    "target_time_seconds": 600,
    "elapsed_time_seconds": 650,
    "late_at": "2026-01-18T14:43:20Z"
  }
}

kds.ticket.recalled​

Ticket brought back.

{
  "event": "kds.ticket.recalled",
  "data": {
    "id": "ticket-001",
    "order_id": "order-12345",
    "station": "grill",
    "reason": "Customer modification",
    "recalled_at": "2026-01-18T14:45:00Z"
  }
}

Inventory Events​

inventory.low_stock​

Item below par level.

{
  "event": "inventory.low_stock",
  "data": {
    "id": "inv-chicken",
    "name": "Chicken Breast",
    "current_quantity": 25,
    "par_level": 50,
    "unit": "lb",
    "reorder_point": 30,
    "severity": "warning"
  }
}

inventory.out_of_stock​

Item depleted.

{
  "event": "inventory.out_of_stock",
  "data": {
    "id": "inv-chicken",
    "name": "Chicken Breast",
    "affected_menu_items": [
      {"id": "item-chicken-sandwich", "name": "Chicken Sandwich"},
      {"id": "item-chicken-salad", "name": "Chicken Salad"}
    ],
    "auto_86ed": true
  }
}

inventory.received​

Stock delivered.

{
  "event": "inventory.received",
  "data": {
    "purchase_order": "po-12345",
    "supplier": "Sysco",
    "items": [
      {
        "id": "inv-chicken",
        "name": "Chicken Breast",
        "quantity_received": 100,
        "new_quantity": 125
      }
    ],
    "received_at": "2026-01-18T08:00:00Z"
  }
}

Table Events​

table.seated​

Guests seated.

{
  "event": "table.seated",
  "data": {
    "table_id": "table-07",
    "table_name": "Table 7",
    "party_size": 4,
    "server": {
      "id": "user-sarah",
      "name": "Sarah"
    },
    "order_id": "order-12345",
    "seated_at": "2026-01-18T14:30:00Z"
  }
}

table.cleared​

Table available.

{
  "event": "table.cleared",
  "data": {
    "table_id": "table-07",
    "table_name": "Table 7",
    "previous_order": "order-12345",
    "turn_time_minutes": 52,
    "cleared_at": "2026-01-18T15:22:00Z"
  }
}

table.reserved​

Reservation assigned.

{
  "event": "table.reserved",
  "data": {
    "table_id": "table-07",
    "reservation": {
      "id": "res-abc123",
      "name": "Smith Party",
      "party_size": 4,
      "time": "18:00"
    }
  }
}

Analytics Events​

analytics.metric_update​

Real-time metric change.

{
  "event": "analytics.metric_update",
  "data": {
    "metrics": {
      "revenue_today": 4250.00,
      "orders_today": 145,
      "avg_ticket": 29.31,
      "guests_today": 312
    },
    "changes": {
      "revenue_today": {
        "previous": 4185.00,
        "change": 65.00
      }
    }
  }
}

analytics.hourly_summary​

Hourly rollup.

{
  "event": "analytics.hourly_summary",
  "data": {
    "hour": "14:00",
    "revenue": 650.00,
    "orders": 18,
    "avg_ticket": 36.11,
    "vs_last_week": {
      "revenue_change": 12.5,
      "orders_change": 8.3
    }
  }
}

Notification Events​

notification.alert​

System alert.

{
  "event": "notification.alert",
  "data": {
    "id": "alert-001",
    "type": "kitchen_backed_up",
    "severity": "warning",
    "title": "Kitchen Queue Alert",
    "message": "Kitchen has 15+ tickets in queue",
    "action_required": true,
    "action_url": "/kitchen/queue"
  }
}

notification.message​

User message.

{
  "event": "notification.message",
  "data": {
    "id": "msg-001",
    "from": {
      "id": "user-manager",
      "name": "John Manager"
    },
    "message": "Please check table 5, customer has a question",
    "priority": "normal"
  }
}

Delivery Events​

delivery.order_received​

New delivery order.

{
  "event": "delivery.order_received",
  "data": {
    "id": "del-12345",
    "platform": "doordash",
    "platform_order_id": "dd-abc123",
    "customer": {
      "name": "John Smith"
    },
    "items_count": 3,
    "total": 46.37,
    "prep_time_minutes": 20
  }
}

delivery.driver_assigned​

Driver on the way.

{
  "event": "delivery.driver_assigned",
  "data": {
    "id": "del-12345",
    "driver": {
      "name": "Mike D.",
      "eta_minutes": 8
    }
  }
}

delivery.picked_up​

Order collected.

{
  "event": "delivery.picked_up",
  "data": {
    "id": "del-12345",
    "picked_up_at": "2026-01-18T12:32:00Z",
    "estimated_delivery": "2026-01-18T12:55:00Z"
  }
}

Voice AI Events​

voice.session_started​

Voice session began.

{
  "event": "voice.session_started",
  "data": {
    "session_id": "voice-sess-abc123",
    "channel": "drive_thru",
    "lane": 1,
    "started_at": "2026-01-18T14:30:00Z"
  }
}

voice.order_completed​

Voice order finished.

{
  "event": "voice.order_completed",
  "data": {
    "session_id": "voice-sess-abc123",
    "order_id": "order-12345",
    "total": 32.60,
    "duration_seconds": 145
  }
}

Error Events​

error​

Connection or subscription error.

{
  "type": "error",
  "code": "subscription_failed",
  "message": "Not authorized for channel",
  "channel": "orders",
  "subscription_id": "sub-001"
}