Notifications

Endpoints for managing notification configuration, querying notification history, and working with push subscriptions.

All notification endpoints are under /api/notifications and require authentication.

AI Review supports multiple notification channels: email, Slack, webhook, WeChat Work (企业微信), DingTalk (钉钉), Feishu (飞书), and browser push.

---

Get notification config

GET /api/notifications/config

Returns the current notification configuration.

curl -X GET https://your-domain.com/api/notifications/config \
  -H "Authorization: Bearer <api-key>"

Response 200

data.config · object

Show Config fields

emailEnabled · boolean

Whether email notifications are enabled.

smtpHost · string | null

SMTP server hostname.

smtpPort · number | null

SMTP port number.

smtpSecure · boolean

Use TLS for SMTP. Default: true.

emailFrom · string | null

Sender email address.

emailRecipients · array

List of recipient email addresses.

webhookEnabled · boolean

Whether outbound webhook notifications are enabled.

webhookUrls · array

List of outbound webhook URLs.

slackEnabled · boolean

Whether Slack notifications are enabled.

slackChannels · array

List of Slack channel IDs.

wechatEnabled · boolean

Whether WeChat Work notifications are enabled.

dingtalkEnabled · boolean

Whether DingTalk notifications are enabled.

feishuEnabled · boolean

Whether Feishu notifications are enabled.

pushEnabled · boolean

Whether browser push notifications are enabled.

notifyOnReviewCompleted · boolean

Send a notification when a review completes.

notifyOnReviewFailed · boolean

Send a notification when a review fails.

notifyOnRatingLow · boolean

Send a notification when a review rating is below the threshold.

ratingThreshold · number

Quality score threshold for low-rating alerts. Default: 70.

notificationFrequency · string

immediate | daily | weekly

---

Create or replace notification config

POST /api/notifications/config

Creates or completely replaces the notification configuration. Requires config:update permission.

curl -X POST https://your-domain.com/api/notifications/config \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "emailEnabled": true,
    "smtpHost": "smtp.example.com",
    "smtpPort": 587,
    "emailFrom": "[e-mail]",
    "emailRecipients": ["[e-mail]"],
    "notifyOnReviewCompleted": true
  }'

The request body accepts any field from the notification config schema.

Response 200

data.config · object

The saved notification config.

---

Partially update notification config

PATCH /api/notifications/config

Updates only the provided fields in the notification config. Requires config:update permission.

Send only the fields you want to change. All other fields remain unchanged.

---

Test a notification channel

POST /api/notifications/config/test-channel

Sends a test notification through the specified channel to verify the configuration is working.

Request body

channel · string · required

The channel to test: email | webhook | slack | wechat | dingtalk | feishu | push.

Response 200

data.result · object

Test result details including success status and any error message.

---

Generate VAPID keys

POST /api/notifications/config/generate-vapid-keys

Generates a new VAPID key pair for use with browser push notifications. Requires config:update permission.

Store the private key securely — it cannot be recovered after leaving this response.

curl -X POST https://your-domain.com/api/notifications/config/generate-vapid-keys \
  -H "Authorization: Bearer <api-key>"

Response 200

data.keys · object

Show VAPID key fields

publicKey · string

The VAPID public key (share with browser clients).

privateKey · string

The VAPID private key (store securely on the server).

---

List notification history

GET /api/notifications

Returns a paginated list of notification history records.

curl -X GET "https://your-domain.com/api/notifications?page=1&pageSize=20" \
  -H "Authorization: Bearer <api-key>"

page · number

Page number. Default: 1.

pageSize · number

Items per page.

channel · string

Filter by channel: email | webhook | slack | wechat | dingtalk | feishu | push.

status · string

Filter by delivery status: pending | sent | failed.

notificationType · string

Filter by event type: review_completed | review_failed | rating_low | daily_summary | weekly_summary.

reviewId · string

Filter by review UUID.

startDate · string

ISO 8601 start date.

endDate · string

ISO 8601 end date.

Response 200

data.items · array

Show History record fields

id · string

Record UUID.

reviewId · string | null

Associated review UUID.

channel · string

Delivery channel used.

notificationType · string

Event type that triggered the notification.

recipient · string | null

Recipient address or identifier.

status · string

pending | sent | failed

errorMessage · string | null

Error detail if delivery failed.

sentAt · string | null

ISO 8601 timestamp when the notification was sent.

createdAt · string

ISO 8601 creation timestamp.

---

Get a notification history record

GET /api/notifications/history/:id

id · string · required

Notification history record ID.

Response 200

data.notification · object

Single notification history record.

---

Get notification statistics

GET /api/notifications/stats

Returns delivery statistics aggregated by channel and status.

startDate · string

ISO 8601 start date for the statistics window.

endDate · string

ISO 8601 end date for the statistics window.

Response 200

data.stats · object

Aggregated notification statistics.

---

Get pending notifications

GET /api/notifications/pending

Returns all notifications currently in pending status (awaiting delivery).

---

Get failed notifications

GET /api/notifications/failed

Returns all notifications with failed delivery status.

---

Clean old notifications

POST /api/notifications/clean

Deletes notification history records older than the specified number of days. Requires notification:delete permission.

Request body

days · number · required

Delete records older than this many days.

Response 200

data.deleted · number

Number of records deleted.

---

Push subscription management

Subscribe to push notifications

POST /api/notifications/push/subscribe

Registers a browser push subscription endpoint.

Request body

endpoint · string · required

The push subscription endpoint URL from the browser.

keys · object · required

Show Key fields

p256dh · string · required

P-256 Diffie-Hellman public key.

auth · string · required

Authentication secret.

List all push subscriptions

GET /api/notifications/push/subscriptions

Returns all registered push subscriptions.

Get push subscriptions for a user

GET /api/notifications/push/users/:userId

userId · string · required

User ID whose subscriptions to retrieve.

Update subscription last-used timestamp

POST /api/notifications/push/touch

endpoint · string · required

The push subscription endpoint to update.

Unsubscribe from push notifications

DELETE /api/notifications/push/unsubscribe

endpoint · string · required

The push subscription endpoint to remove.

Clean expired push subscriptions

POST /api/notifications/push/clean

Deletes all expired push subscriptions. Requires notification:delete permission.