1.8 Notification

This document covers the three non-workflow notification types and the shared mark-as-read endpoint. All endpoints live under /api/notifications/.

1.8.1 Overview

These APIs are designed to be called by backend services (e.g. the scan engine, the VulSource sync job) rather than directly by end-users. The caller provides the delivery target (recipient) and the userId is retained so the frontend can query notifications per user.

Concept	Description
userId	Identifies the user in the frontend. Used to query notifications later.
recipient	The actual delivery address (email, phone). Decoupled from the user table.
read	Boolean on every notification. Starts false, set to true via the API.

1.8.2 Architecture

1.8.3 Notification Types

Type	Value in DB	Required Fields	Stored in Metadata
VulSource Update	vulsource_update	userId, recipient, versionNumber	version_number
Scan Failed	scan_failed	userId, recipient, projectId	project_id
Scheduled Scan Finished	scheduled_scan_finished	userId, recipient, projectId	project_id

1.8.4 API Reference

1. VulSource Update

Send a notification when the vulnerability source database is updated to a new version.

POST /api/notifications/vulsource-update

Request Body

{
  "userId": "user-123",
  "recipient": "alice@example.com",
  "versionNumber": "2.4.1"
}

Field	Type	Required	Description
userId	string	Yes	User ID for frontend correlation
recipient	string	Yes	Email address to deliver the notification to
versionNumber	string	Yes	The new VulSource database version number

Response — 200 OK

{
  "message": "VulSource update notification sent successfully"
}

2. Scan Failed

Send a notification when a project scan fails.

POST /api/notifications/scan-failed

Request Body

{
  "userId": "user-456",
  "recipient": "bob@example.com",
  "projectId": "proj-001"
}

Field	Type	Required	Description
userId	string	Yes	User ID for frontend correlation
recipient	string	Yes	Email address to deliver the notification to
projectId	string	Yes	The project whose scan failed

Response — 200 OK

{
  "message": "Scan failed notification sent successfully"
}

3. Scheduled Scan Finished

Send a notification when a scheduled scan completes successfully.

POST /api/notifications/scheduled-scan-finished

Request Body

{
  "userId": "user-789",
  "recipient": "carol@example.com",
  "projectId": "proj-002"
}

Field	Type	Required	Description
userId	string	Yes	User ID for frontend correlation
recipient	string	Yes	Email address to deliver the notification to
projectId	string	Yes	The project whose scheduled scan finished

Response — 200 OK

{
  "message": "Scheduled scan finished notification sent successfully"
}

4. Mark Notification as Read

Mark a single notification as read. Applies to all notification types.

PUT /api/notifications/:notificationId/read

Path Parameters

Parameter	Type	Description
notificationId	string	The notification's ID

Response — 200 OK

{
  "message": "Notification marked as read",
  "notification": {
    "id": "abc-123",
    "userId": "user-123",
    "type": "vulsource_update",
    "channel": "email",
    "title": "VulSource Database Updated",
    "message": "...",
    "status": "sent",
    "read": true,
    "recipient": "alice@example.com",
    "metadata": { "version_number": "2.4.1" },
    "createdAt": "2026-02-13T12:00:00Z",
    "sentAt": "2026-02-13T12:00:01Z"
  }
}

5. Get User Notifications

Retrieve all notifications for a user (including both workflow and non-workflow types). This is the endpoint the frontend calls to populate the notification panel.

GET /api/workflow/users/:userId/notifications?limit=20&offset=0

Response — 200 OK

{
  "notifications": [
    {
      "id": "abc-123",
      "userId": "user-123",
      "type": "vulsource_update",
      "read": false,
      "title": "VulSource Database Updated",
      "status": "sent",
      "createdAt": "2026-02-13T12:00:00Z"
    }
  ],
  "total": 1
}

1.8.5 Notification Lifecycle

1.8.6 Use-Case Examples

Broadcast VulSource Update to All Users

When the VulSource sync job finishes and a new version is available, broadcast a notification to every subscribed user. The calling service owns the user list and iterates over it.

Caller pseudocode:

new_version = "2.4.1"
users = user_db.get_users_subscribed_to("vulsource_update")

for user in users:
    requests.post(
        "http://localhost:3008/api/notifications/vulsource-update",
        json={
            "userId": user.id,
            "recipient": user.email,
            "versionNumber": new_version,
        },
    )

Alert a User When Their Scan Fails

The scan engine detects a failure and immediately notifies the project owner.

Caller pseudocode:

requests.post(
    "http://localhost:3008/api/notifications/scan-failed",
    json={
        "userId": project.owner_id,
        "recipient": project.owner_email,
        "projectId": project.id,
    },
)

Notify on Scheduled Scan Completion

A cron-triggered scan finishes; the scheduler notifies the user so they can review results.

Caller pseudocode:

requests.post(
    "http://localhost:3008/api/notifications/scheduled-scan-finished",
    json={
        "userId": project.owner_id,
        "recipient": project.owner_email,
        "projectId": project.id,
    },
)

1.8.7 Error Responses

All endpoints return errors in the same format:

{ "error": "description of the error" }

HTTP Status	Meaning
400	Missing or invalid required fields
404	User or notification not found
500	Internal error (DB write failure, email failure)