Notification Events¶

Notification events deliver and acknowledge user notifications over the socket. The delivery channel is the notifications room (see rooms.md).

Both events below are part of the documented contract and are planned in the current server build; the notification engine is the same system that powers in-app and push notifications.

Reference: rooms.md · errors.md · rate-limits.md

Event list¶

notification.created¶

Description¶

Pushed to a user when a notification is created (e.g. bid outbid, auction started, winner declared, payment reminders). The server routes it to the recipient's connections — typically via the user:<id> room or the notifications room — with the notification payload.

Direction¶

Server → Client

Roles Allowed¶

All roles.

Permissions Required¶

None for receiving (delivery is based on the recipient's rooms).

Request Schema¶

N/A — server-pushed.

Response Schema¶

Example Response¶

{
  "type": "notification.created",
  "data": {
    "notificationId": "noti_01HQ5BY3K7Z2V6Y0W5X0W5X0W5X",
    "type": "AUCTION_OUTBID",
    "title": "You've been outbid",
    "body": "Annie Mohan placed a higher bid of 25000",
    "data": {
      "cycleId": "cyc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X",
      "auctionId": "auc_01HQ5BWNJ5Y1P5RX0W5X0W5X0W5X"
    },
    "createdAt": "2026-08-03T10:00:05.000Z"
  }
}

Error Responses¶

None (server-pushed).

Validation Rules¶

N/A (server-generated).

Broadcast Behaviour¶

Targeted to the receiving user (all their open connections), not broadcast to the whole platform.

Related Events¶

• notification.read

Notes¶

• Implementation status: Planned.
• The payload is informative and matches the REST notification model.

Best Practices¶

• Idempotently upsert notifications by notificationId.
• Show a system-level toast/local notification only as a UX enhancement; keep the REST notification list as source of truth.

notification.read¶

Marks a notification as read. This is a client→server command that writes read state.

Direction¶

Client → Server

Roles Allowed¶

All roles (a user marks their own notifications).

Permissions Required¶

notification:read (planned). Enforced at the route level when implemented.

Request Schema¶

Response Schema¶

Success Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y5RX0W5X0W5X0W5X",
  "eventType": "notification.read",
  "data": {
    "notificationId": "noti_01HQ5BYN1K7Z2V6Y0W5X0W5X0W5X",
    "read": true
  }
}

Error Responses¶

Validation Rules¶

Example Request¶

{
  "type": "notification.read",
  "requestId": "req_01HQ5BXWYP1Y2RX0W5X0W5X0W5X",
  "data": { "notificationId": "noti_01HQ5BYN1K7ZRX0W5X0W5X0W5X" }
}

Example Response¶

{
  "type": "ack",
  "requestId": "req_01HQ5BXWYP1Y2RX0W5X0W5X0W5X",
  "eventType": "notification.read",
  "data": {
    "notificationId": "noti_01HQ5BYN1K7ZRX0W5X0W5X0W5X",
    "read": true
  }
}

Broadcast Behaviour¶

None; affects the owner's read state only. Other connections of the same user may receive a state refresh via their private channel when implemented.

Related Events¶

• notification.created
• events/chat.md, events/system.md

Notes¶

• Implementation status: Planned. The route is not yet registered.
• Marking read is idempotent by notificationId.

Best Practices¶

• Send only for the current user's notifications.
• Batch marker-reads into the REST bulk-mark endpoint if you have many; reserve the socket for single immediate marks.

Related documents¶

• rooms.md — notifications and user:<id> rooms.
• errors.md — error codes.
• events/auction.md — auction events that produce notifications.