Sep 11, 2025 · Sep 9, 2025 · Sep 10, 2025 · Sep 10, 2025 · Sep 10, 2025 · Sep 10, 2025
diff --git a/cli/notifications.go b/cli/notifications.go
 Short: "Manage Coder notifications",
 Long: "Administrators can use these commands to change notification settings.\n" + FormatExamples(
 Example{
 Description: "Pause Coder notifications. Administrators can temporarily stop notifiers from dispatching messages in case of the target outage (for example: unavailable SMTP server or Webhook not responding).",
 Description: "Pause Coder notifications. Administrators can temporarily stop notifiers from dispatching messages in case of the target outage (for example: unavailable SMTP server or Webhook not responding)",
 Command:     "coder notifications pause",
 },
 Example{
 Description: "Resume Coder notifications",
 Command:     "coder notifications resume",
 },
 Example{
 Description: "Send a test notification. Administrators can use this to verify the notification target settings.",
 Description: "Send a test notification. Administrators can use this to verify the notification target settings",
 Command:     "coder notifications test",
 },
 Example{
 Description: "Send a custom notification to the requesting user. The recipient is always the requesting user as targeting other users or groups isn’t supported yet",
 Command:     "coder notifications custom \"Custom Title\" \"Custom Message\"",
 },
 ),
 Aliases: []string{"notification"},
 Handler: func(inv *serpent.Invocation) error {
 r.pauseNotifications(),
 r.resumeNotifications(),
 r.testNotifications(),
 r.customNotifications(),
 },
 }
 return cmd
 }
 return cmd
 }

 func (r *RootCmd) customNotifications() *serpent.Command {
 client := new(codersdk.Client)
 cmd := &serpent.Command{
 Use:   "custom <title> <message>",
 Short: "Send a custom notification",
 Middleware: serpent.Chain(
 serpent.RequireNArgs(2),
 r.InitClient(client),
 ),
 Handler: func(inv *serpent.Invocation) error {
 err := client.PostCustomNotification(inv.Context(), codersdk.CustomNotification{
 Title:   inv.Args[0],
 Message: inv.Args[1],
 })
 if err != nil {
 return xerrors.Errorf("unable to post custom notification: %w", err)
 }

 _, _ = fmt.Fprintln(inv.Stderr, "A custom notification has been sent.")
 return nil
 },
 }
 return cmd
 }
diff --git a/cli/notifications_test.go b/cli/notifications_test.go
 require.Len(t, sent, 0)
 })
 }

 func TestCustomNotifications(t *testing.T) {
 t.Parallel()

 t.Run("BadRequest", func(t *testing.T) {
 t.Parallel()

 notifyEnq := &notificationstest.FakeEnqueuer{}

 // Given: A member user
 ownerClient := coderdtest.New(t, &coderdtest.Options{
 DeploymentValues:      coderdtest.DeploymentValues(t),
 NotificationsEnqueuer: notifyEnq,
 })
 ownerUser := coderdtest.CreateFirstUser(t, ownerClient)
 memberClient, _ := coderdtest.CreateAnotherUser(t, ownerClient, ownerUser.OrganizationID)

 // When: The member user attempts to send a custom notification with empty title and message
 inv, root := clitest.New(t, "notifications", "custom", "", "")
 clitest.SetupConfig(t, memberClient, root)

 // Then: an error is expected with no notifications sent
 err := inv.Run()
 var sdkError *codersdk.Error
 require.Error(t, err)
 require.ErrorAsf(t, err, &sdkError, "error should be of type *codersdk.Error")
 assert.Equal(t, http.StatusBadRequest, sdkError.StatusCode())
 require.Equal(t, "Invalid request body", sdkError.Message)

 sent := notifyEnq.Sent(notificationstest.WithTemplateID(notifications.TemplateTestNotification))
 require.Len(t, sent, 0)
 })

 t.Run("Success", func(t *testing.T) {
 t.Parallel()

 notifyEnq := &notificationstest.FakeEnqueuer{}

 // Given: A member user
 ownerClient := coderdtest.New(t, &coderdtest.Options{
 DeploymentValues:      coderdtest.DeploymentValues(t),
 NotificationsEnqueuer: notifyEnq,
 })
 ownerUser := coderdtest.CreateFirstUser(t, ownerClient)
 memberClient, memberUser := coderdtest.CreateAnotherUser(t, ownerClient, ownerUser.OrganizationID)

 // When: The member user attempts to send a custom notification
 inv, root := clitest.New(t, "notifications", "custom", "Custom Title", "Custom Message")
 clitest.SetupConfig(t, memberClient, root)

 // Then: we expect a custom notification to be sent to the member user
 err := inv.Run()
 require.NoError(t, err)

 sent := notifyEnq.Sent(notificationstest.WithTemplateID(notifications.TemplateCustomNotification))
 require.Len(t, sent, 1)
 require.Equal(t, memberUser.ID, sent[0].UserID)
 require.Len(t, sent[0].Labels, 2)
 require.Equal(t, "Custom Title", sent[0].Labels["custom_title"])
 require.Equal(t, "Custom Message", sent[0].Labels["custom_message"])
 require.Equal(t, memberUser.ID.String(), sent[0].CreatedBy)
 })
 }
diff --git a/cli/testdata/coder_notifications_--help.golden b/cli/testdata/coder_notifications_--help.golden
  from
  dispatching messages in case of the target outage (for example: unavailable
  SMTP
  server or Webhook not responding).:
  server or Webhook not responding):

       $ coder notifications pause


    - Send a test notification. Administrators can use this to verify the
  notification
  target settings.:
  target settings:

       $ coder notifications test

    - Send a custom notification to the requesting user. The recipient is always
  the
  requesting user as targeting other users or groups isn’t supported yet:

       $ coder notifications custom "Custom Title" "Custom Message"

 SUBCOMMANDS:
    custom    Send a custom notification
    pause     Pause notifications
    resume    Resume notifications
    test      Send a test notification
diff --git a/cli/testdata/coder_notifications_custom_--help.golden b/cli/testdata/coder_notifications_custom_--help.golden
 coder v0.0.0-devel

 USAGE:
  coder notifications custom <title> <message>

  Send a custom notification

 ———
 Run `coder --help` for a list of global options.
diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go
diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json
diff --git a/coderd/coderd.go b/coderd/coderd.go
 })
 r.Get("/dispatch-methods", api.notificationDispatchMethods)
 r.Post("/test", api.postTestNotification)
 r.Post("/custom", api.postCustomNotification)
 })
 r.Route("/tailnet", func(r chi.Router) {
 r.Use(apiKeyMiddleware)
diff --git a/coderd/database/migrations/000367_add_custom_notifications.down.sql b/coderd/database/migrations/000367_add_custom_notifications.down.sql
 DELETE FROM notification_templates WHERE id = '39b1e189-c857-4b0c-877a-511144c18516';

diff --git a/coderd/database/migrations/000367_add_custom_notifications.up.sql b/coderd/database/migrations/000367_add_custom_notifications.up.sql
 INSERT INTO notification_templates (
 id,
 name,
 title_template,
 body_template,
 actions,
 "group",
 method,
 kind,
 enabled_by_default
 )VALUES (
 '39b1e189-c857-4b0c-877a-511144c18516',
 'Custom Notification',
 '{{.Labels.custom_title}}',
 '{{.Labels.custom_message}}',
 '[]',
 'Custom Events',
 NULL,
 'system'::notification_template_kind,
 true
 );
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,17 +16,21 @@ func (r RootCmd) notifications() serpent.Command {
		Short: "Manage Coder notifications",
		Long: "Administrators can use these commands to change notification settings.\n" + FormatExamples(
		Example{
		Description: "Pause Coder notifications. Administrators can temporarily stop notifiers from dispatching messages in case of the target outage (for example: unavailable SMTP server or Webhook not responding).",
		Description: "Pause Coder notifications. Administrators can temporarily stop notifiers from dispatching messages in case of the target outage (for example: unavailable SMTP server or Webhook not responding)",
		Command: "coder notifications pause",
		},
		Example{
		Description: "Resume Coder notifications",
		Command: "coder notifications resume",
		},
		Example{
		Description: "Send a test notification. Administrators can use this to verify the notification target settings.",
		Description: "Send a test notification. Administrators can use this to verify the notification target settings",
		Command: "coder notifications test",
		},
		Example{
		Description: "Send a custom notification to the requesting user. The recipient is always the requesting user as targeting other users or groups isn’t supported yet",
ssncferreira marked this conversation as resolved. OutdatedShow resolvedHide resolved
		Command: "coder notifications custom \"Custom Title\" \"Custom Message\"",
		},
		),
		Aliases: []string{"notification"},
		Handler: func(inv *serpent.Invocation) error {
Expand All		@@ -36,6 +40,7 @@ func (r RootCmd) notifications() serpent.Command {
		r.pauseNotifications(),
		r.resumeNotifications(),
		r.testNotifications(),
		r.customNotifications(),
		},
		}
		return cmd
Expand DownExpand Up		@@ -109,3 +114,28 @@ func (r RootCmd) testNotifications() serpent.Command {
		}
		return cmd
		}

		func (r RootCmd) customNotifications() serpent.Command {
		client := new(codersdk.Client)
		cmd := &serpent.Command{
		Use: "custom <title> <message>",
		Short: "Send a custom notification",
		Middleware: serpent.Chain(
		serpent.RequireNArgs(2),
		r.InitClient(client),
		),
		Handler: func(inv *serpent.Invocation) error {
		err := client.PostCustomNotification(inv.Context(), codersdk.CustomNotification{
		Title: inv.Args[0],
		Message: inv.Args[1],
		})
		if err != nil {
		return xerrors.Errorf("unable to post custom notification: %w", err)
		}

		_, _ = fmt.Fprintln(inv.Stderr, "A custom notification has been sent.")
		return nil
		},
		}
		return cmd
		}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -166,3 +166,66 @@ func TestNotificationsTest(t *testing.T) {
		require.Len(t, sent, 0)
		})
		}

		func TestCustomNotifications(t *testing.T) {
		t.Parallel()

		t.Run("BadRequest", func(t *testing.T) {
		t.Parallel()

		notifyEnq := &notificationstest.FakeEnqueuer{}

		// Given: A member user
		ownerClient := coderdtest.New(t, &coderdtest.Options{
		DeploymentValues: coderdtest.DeploymentValues(t),
		NotificationsEnqueuer: notifyEnq,
		})
		ownerUser := coderdtest.CreateFirstUser(t, ownerClient)
		memberClient, _ := coderdtest.CreateAnotherUser(t, ownerClient, ownerUser.OrganizationID)

		// When: The member user attempts to send a custom notification with empty title and message
		inv, root := clitest.New(t, "notifications", "custom", "", "")
		clitest.SetupConfig(t, memberClient, root)

		// Then: an error is expected with no notifications sent
		err := inv.Run()
		var sdkError *codersdk.Error
		require.Error(t, err)
		require.ErrorAsf(t, err, &sdkError, "error should be of type *codersdk.Error")
		assert.Equal(t, http.StatusBadRequest, sdkError.StatusCode())
		require.Equal(t, "Invalid request body", sdkError.Message)

		sent := notifyEnq.Sent(notificationstest.WithTemplateID(notifications.TemplateTestNotification))
		require.Len(t, sent, 0)
		})

		t.Run("Success", func(t *testing.T) {
		t.Parallel()

		notifyEnq := &notificationstest.FakeEnqueuer{}

		// Given: A member user
		ownerClient := coderdtest.New(t, &coderdtest.Options{
		DeploymentValues: coderdtest.DeploymentValues(t),
		NotificationsEnqueuer: notifyEnq,
		})
		ownerUser := coderdtest.CreateFirstUser(t, ownerClient)
		memberClient, memberUser := coderdtest.CreateAnotherUser(t, ownerClient, ownerUser.OrganizationID)

		// When: The member user attempts to send a custom notification
		inv, root := clitest.New(t, "notifications", "custom", "Custom Title", "Custom Message")
		clitest.SetupConfig(t, memberClient, root)

		// Then: we expect a custom notification to be sent to the member user
		err := inv.Run()
		require.NoError(t, err)

		sent := notifyEnq.Sent(notificationstest.WithTemplateID(notifications.TemplateCustomNotification))
		require.Len(t, sent, 1)
		require.Equal(t, memberUser.ID, sent[0].UserID)
		require.Len(t, sent[0].Labels, 2)
		require.Equal(t, "Custom Title", sent[0].Labels["custom_title"])
		require.Equal(t, "Custom Message", sent[0].Labels["custom_message"])
		require.Equal(t, memberUser.ID.String(), sent[0].CreatedBy)
		})
		}
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,7 +12,7 @@ USAGE:
		from
		dispatching messages in case of the target outage (for example: unavailable
		SMTP
		server or Webhook not responding).:
		server or Webhook not responding):

		$ coder notifications pause

Expand All		@@ -22,11 +22,18 @@ USAGE:

		- Send a test notification. Administrators can use this to verify the
		notification
		target settings.:
		target settings:

		$ coder notifications test

		- Send a custom notification to the requesting user. The recipient is always
		the
		requesting user as targeting other users or groups isn’t supported yet:

		$ coder notifications custom "Custom Title" "Custom Message"

		SUBCOMMANDS:
		custom Send a custom notification
		pause Pause notifications
		resume Resume notifications
		test Send a test notification
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,9 @@
		coder v0.0.0-devel

		USAGE:
		coder notifications custom <title> <message>

		Send a custom notification

		———
		Run `coder --help` for a list of global options.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1581,6 +1581,7 @@ func New(options Options) API {
		})
		r.Get("/dispatch-methods", api.notificationDispatchMethods)
		r.Post("/test", api.postTestNotification)
		r.Post("/custom", api.postCustomNotification)
		})
		r.Route("/tailnet", func(r chi.Router) {
		r.Use(apiKeyMiddleware)
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		DELETE FROM notification_templates WHERE id = '39b1e189-c857-4b0c-877a-511144c18516';
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,21 @@
		INSERT INTO notification_templates (
		id,
		name,
		title_template,
		body_template,
		actions,
		"group",
		method,
		kind,
		enabled_by_default
		)VALUES (
		'39b1e189-c857-4b0c-877a-511144c18516',
		'Custom Notification',
		'{{.Labels.custom_title}}',
		'{{.Labels.custom_message}}',
		'[]',
		'Custom Events',
		NULL,
		'system'::notification_template_kind,
Copy link ContributorAuthor ssncferreiraSep 10, 2025• edited Loading 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 johnstcnSep 10, 2025 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. ssncferreira reacted with thumbs up emoji Copy link ContributorAuthor ssncferreiraSep 10, 2025 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
		true
		);