Skip to content

Conversation

ssncferreira
Copy link
Contributor

@ssncferreira ssncferreira commented Sep 9, 2025

Description

Adds support for sending an ad‑hoc custom notification to the authenticated user via API and CLI. This is useful for surfacing the result of scripts or long‑running tasks. Notifications are delivered through the configured method and the dashboard Inbox, respecting existing preferences and delivery settings.

Changes

  • New notification template: “Custom Notification” with a label for a custom title and a custom message.
  • New API endpoint: POST /api/v2/notifications/custom to send a custom notification to the requesting user.
  • New API endpoint: GET /notifications/templates/custom to get custom notification template.
  • New CLI subcommand: coder notifications custom <title> <message> to send a custom notification to the requesting user.
  • Documentation updates: Add a “Custom notifications” section under Administration > Monitoring > Notifications, including instructions on sending custom notifications and examples of when to use them.

Closes: #19611

@ssncferreira ssncferreira changed the title feat: Support custom notifications feat: support custom notifications Sep 9, 2025
@ssncferreira ssncferreira force-pushed the ssncferreira/support_custom_notifications branch 4 times, most recently from ae71b80 to 35579a8 Compare September 10, 2025 10:12
@ssncferreira ssncferreira force-pushed the ssncferreira/support_custom_notifications branch from 35579a8 to 2ab1c4d Compare September 10, 2025 10:25
'[]',
'Custom Events',
NULL,
'system'::notification_template_kind,
Copy link
Contributor Author

@ssncferreira ssncferreira Sep 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might make sense to introduce a new notification kind custom rather than reusing system. system notifications are triggered by events within the system, whereas this custom notification is user-initiated and typically relates to events happening outside the system.

This would also require adding a /notifications/custom endpoint and updating the front-end (e.g., /deployment/notifications) to retrieve both system and custom templates.

Wdyt?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should do this. I don't like the idea of piggy-backing on top of "system" notifications here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Addressed in 203668d
I will add the front-end changes to /deployment/notifications in a follow-up PR

}

userID := apiKey.UserID
if _, err := api.NotificationsEnqueuer.Enqueue(
Copy link
Contributor Author

@ssncferreira ssncferreira Sep 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: Custom notifications may have the same issue as test notifications, if a user sends the same notification multiple times in a single day, our deduping will treat later sends as duplicates. Changing this could also mean circumventing a measure intended to reduce noise and prevent spam. For now this shouldn’t be a problem since users can only send notifications to themselves, but that might change in the future.

Should we allow multiple sends of the same custom notification within a single day, or keep the current deduping to limit noise/spam?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point. I would suggest:

  • For requestors sending a notification to themselves, do not dedupe OR reduce the deduplication timeframe to something lower like 1 minute.
  • For requestors sending a notification to others, we should enforce similar notification limits to prevent noise.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a user has some script that alerts them of completion of a task, it might make sense for their notification to have the same content each time. It would definitely be surprising for them to not receive the second one.

If we keep the de-duplicate behavior then we definitely need to ensure this behavior is very obviously documented. We could document a workaround that the user can do by injecting a timestamp in the message.

I'm not opposed to us bypassing the de-duplication logic and just ensuring this endpoint has a rate limit? Would like to hear other peoples thoughts on that though.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@johnstcn @DanielleMaywood Thank you for the feedback. I agree that for the custom notification use case, it might be common to send the same message multiple times in a day, so it makes sense not to dedupe those. Since this feature will evolve to support multiple recipients, I like the idea of not deduping for the requesting user while deduping for other recipients.
For now, I updated the code to bypass deduplication by adding a timestamp to the payload (same as in test notifications).
We might be able to update compute_notification_message_dedupe_hash to produce a different hash when it’s a custom notification and the sender is also the recipient.

I created a follow-up issue to track multi-recipient support: #19768

@ssncferreira ssncferreira marked this pull request as ready for review September 10, 2025 10:57
}

userID := apiKey.UserID
if _, err := api.NotificationsEnqueuer.Enqueue(
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point. I would suggest:

  • For requestors sending a notification to themselves, do not dedupe OR reduce the deduplication timeframe to something lower like 1 minute.
  • For requestors sending a notification to others, we should enforce similar notification limits to prevent noise.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice examples!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Obligatory reminder to check migration number before merge¬!

@ssncferreira ssncferreira merged commit eec6c8c into main Sep 11, 2025
56 of 58 checks passed
@ssncferreira ssncferreira deleted the ssncferreira/support_custom_notifications branch September 11, 2025 13:08
@github-actions github-actions bot locked and limited conversation to collaborators Sep 11, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Support custom notifications
3 participants