Events

Events

Events are named messages with a JSON payload that your MockLab project can send to connected clients. You define events in the dashboard, then trigger them manually or automatically via a schedule.

Creating an event

  1. Open your WS project and click the Events tab.
  2. Click Add Event.
  3. Fill in:
    • Event name — the Socket.io event name or WS message type (e.g. order:updated)
    • Payload — a JSON object to send with the event
    • Target — broadcast to all clients, or enter a specific client ID
  4. Click Save. The event appears in the events list.

Event payload format

Example event payloads 
// order:updated — broadcast to all clients
{
  "event": "order:updated",
  "payload": {
    "orderId": "ord_9kXz",
    "status": "shipped",
    "trackingNumber": "1Z999AA10123456784",
    "estimatedDelivery": "2024-11-08"
  },
  "target": "broadcast"
}

// notification:new — send only to one client
{
  "event": "notification:new",
  "payload": {
    "id": "notif_4xPq",
    "type": "mention",
    "message": "@you were mentioned in a comment"
  },
  "target": "client_Yz3xR9"   // specific socket ID
}

Receiving events in your frontend

Socket.io — listen for named events 
socket.on('order:updated', (data) => {
  console.log('Order shipped:', data.orderId);
  updateOrderUI(data);
});

socket.on('notification:new', (data) => {
  showToast(data.message);
});

// For raw WebSocket, parse the message manually:
ws.onmessage = (event) => {
  const { event: name, payload } = JSON.parse(event.data);
  if (name === 'order:updated') updateOrderUI(payload);
};

Triggering events manually

Each event in the dashboard has a Trigger button. Clicking it immediately sends the event to the target (all clients or a specific client ID). This is useful for testing UI reactions to one-off server pushes.

Triggering via API (Pro)

Pro plan users can trigger events programmatically via the MockLab REST API, making it easy to fire events from test suites or CI pipelines.

curl — trigger event via API 
curl -X POST https://api.mocklab.dev/v1/ws-projects/{projectId}/events/{eventId}/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "broadcast",
    "payloadOverride": {
      "orderId": "ord_test_123",
      "status": "delivered"
    }
  }'

Plan limits

Plan Events per project
Free 5 events
Pro 50 events
WebSocket Overview Schedules