TF-33257 HCP Terraform & Enterprise Docs Update Notification Configurations for Projects

[jillirami]

Please go to the Preview tab and select the appropriate template:

Terraform

• HCP Terraform
• Terraform
• Terraform Enterprise

TF-33257

[github-actions]

Vercel Previews Deployed

Name	Status	Preview	Updated (UTC)
Dev Portal	✅ Ready (Inspect)	Visit Preview	Fri Apr 3 23:07:56 UTC 2026
Unified Docs API	✅ Ready (Inspect)	Visit Preview	Fri Apr 3 23:04:06 UTC 2026

[github-actions]

Broken Link Checker

No broken links found! 🎉

[trujillo-adam]

This review is just for the new UI page. I'll branch off of this PR to suggest some structural changes to the API docs. We'll also need to remove the TFE-specific page. If we merge by 4/3, TFE 2.0 will get the new content automatically.

[trujillo-adam]

Suggested change

	-> **API:** Refer to [Project notification configurations API reference](/terraform/cloud-docs/api-docs/project-notification-configurations).
	Refer to [Project notification configurations API reference](/terraform/cloud-docs/api-docs/project-notification-configurations) for information on integrating with your notification systems.

Doesn't need to be a callout box and shouldn't be on the other pages, either.

[trujillo-adam]

Suggested change

	## How project notifications work
	Project notifications work alongside workspace notifications.
	### Apply to all workspaces
	Project notifications trigger for all current workspaces in the project. They also trigger for any workspaces that you create in the project or move into it later.
	### Combine with workspace notifications
	Project notifications do not modify or remove workspace notifications. For example, if a workspace has a Slack webhook and the project has a PagerDuty webhook, the same run event triggers both notifications.
	### Cannot be disabled from workspaces
	Workspace administrators cannot turn off project notifications from workspace settings. You must modify or delete them at the project level.
	## Overview
	HCP Terraform sends project notifications in addition to workspace notifications. Project notifications do not modify or remove workspace notifications. For example, if a workspace has a Slack webhook and the project has a PagerDuty webhook, the same run event triggers both notifications.
	HCP Terraform sends project notifications for all current workspaces in the project. They also trigger for any workspaces that you create in the project or move into it later.
	By default, HCP Terraform also sends project notifications for all current workspaces in the organization, but you can remove them from the scope during configuration.
	Workspace administrators cannot turn off project notifications from workspace settings. You must modify or delete them at the project level.

This is normally call the "Overview" or "Introduction" section in a usage page. The combination of wording in the H2 and the subheadings was a little confusing to me at first because they seemed like settings.

I added the information about the default behavior because that's what I saw on staging, but I don't know if that's intentional.

Just to be clear, once you create a project-level notification, the platform sends a notification to the external app for any of the selected events for all workspaces in the project, period. You can't select the workspaces in the project that trigger the notification. The workspaces field in the UI is to send notifications when workspaces outside the project trigger the notification, correct?

[trujillo-adam]

Ideally, "Notification payloads" is a standalone reference topic. No action on this comment -- it's more for me to investigate a better structure.

[trujillo-adam]

I'll create a subbranch to propose some structural changes that I think will set us up better for future work

[jillirami]

Suggestion to remove changes to this TFE file content/terraform-enterprise/1.1.x/docs/enterprise/api-docs/notification-configurations.mdx until after the release next week, to unblock this PR for TFC