Notifications
Real-time notifications keep your team informed about bookings, payments, check-ins, and other important events as they happen.
Overview
The notification system delivers instant updates to users in your organization via Socket.IO WebSocket connections. When an event occurs (e.g., a new booking is created, a payment is received), all connected users in the organization receive a notification in real-time — no page refresh needed.
How It Works
Key Architecture Points
- No polling — The frontend does not poll the server for new notifications. All updates arrive via Socket.IO events.
- Organization-scoped rooms — Users join a Socket.IO room scoped to their organization (
org:{orgId}). Events are broadcast to all users in that room. - Per-user read tracking — Each notification has a
readBy[]array. The unread count is calculated per user, not globally. - Automatic query invalidation — Socket events automatically invalidate React Query caches, so lists and counts refresh instantly.
Notification Types
| Type | Triggered When |
|---|---|
booking_created | A new booking is created |
booking_updated | A booking is modified |
booking_checked_in | A guest checks in |
booking_checked_out | A guest checks out |
payment_received | A payment is recorded |
invoice_created | An invoice is generated |
guest_created | A new guest is registered |
reminder_checkin | Upcoming check-in reminder (via Apps Script) |
reminder_checkout | Upcoming check-out reminder (via Apps Script) |
overdue_payment | Payment overdue alert (via Apps Script) |
system | System-level notifications |
Frontend UI
Notification Bell
The notification bell icon in the top navigation bar shows:
- Unread count badge — Red badge with the number of unread notifications
- Click to open — Opens a popover with the latest notifications
- Mark as read — Click a notification to mark it as read
- Mark all as read — Button to clear all unread notifications
- View all — Link to the full notifications page
Full Notifications Page
Navigate to Notifications from the sidebar to see the complete notifications interface with two tabs:
| Tab | Description |
|---|---|
| Notifications | Paginated list of all notifications with type badges, timestamps, and mark-as-read controls |
| Settings | Configure which notification types you want to receive |
Real-Time Updates
Notifications update instantly without page refresh:
- Socket.IO event arrives (
notification:created,notification:read, etc.) - React Query cache is automatically invalidated via the Socket Provider
- UI re-renders — bell badge count updates, notification list refreshes
Socket Events
| Event | Direction | Description |
|---|---|---|
notification:created | Server → Client | New notification created |
notification:read | Server → Client | A notification was marked as read |
notification:read_all | Server → Client | All notifications marked as read |
notification:deleted | Server → Client | A notification was deleted |
These events are registered in EVENT_TO_QUERY_KEYS in the Socket Provider, which automatically invalidates the ["notifications"] query key when any notification event arrives.
Configuration
Notification Settings
Each user can configure their notification preferences per organization:
| Setting | Description |
|---|---|
| Enable/Disable by type | Toggle specific notification types on/off |
| Email notifications | Future: receive email copies of notifications |
Settings are managed via the Settings tab on the Notifications page.
Data Retention
- Notifications are automatically cleaned up after 30 days via a scheduled cleanup endpoint
- Audit logs (which may reference notifications) are retained for 365 days
Scheduled Notifications (Google Apps Script)
The system includes a Google Apps Script integration that runs on a schedule to generate proactive notifications:
| Trigger | Frequency | What It Does |
|---|---|---|
| Check-in reminders | Every 4 hours | Alerts for bookings arriving today/tomorrow |
| Check-out reminders | Every 4 hours | Alerts for bookings departing today |
| Overdue payment alerts | Daily (9 AM) | Flags invoices past their due date |
| Notification cleanup | Daily (2 AM) | Removes notifications older than 30 days |
Setup
Google Apps Script triggers are configured separately. See the Integrations guide for setup instructions and Script Properties configuration.
Permissions
Notification access is controlled by the Notifications RBAC module:
| Permission | Access |
|---|---|
| View | See and read notifications |
| Create | Trigger notifications (typically system-only) |
| Update | Mark notifications as read |
| Delete | Delete notifications |
| Manage | Full access including configuration |