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

content/terraform-docs-common/data/cloud-docs-nav-data.json

@@ -165,6 +165,7 @@
           "title": "Manage projects",
           "path": "projects/manage"
         },
+    { "title": "Notifications", "path": "projects/notifications" },
     { "title": "Best practices", "path": "projects/best-practices" }
     ]
   },
@@ -764,10 +765,15 @@
   { "title": "Invoices", "path": "api-docs/invoices" },
   { "title": "IP ranges", "path": "api-docs/ip-ranges" },
   { "title": "No-code provisioning", "path": "api-docs/no-code-provisioning"},
-      {
-        "title": "Notification configurations",
-        "path": "api-docs/notification-configurations"
-      },
+  {
+    "title": "Notification configurations",
+    "routes": [
+      { "title": "Overview", "path": "api-docs/notification-configurations"},
+      { "title": "Workspace", "path": "api-docs/notification-configurations/workspace" },
+      { "title": "Project", "path": "api-docs/notification-configurations/project" },
+      { "title": "Team", "path": "api-docs/notification-configurations/team" }
+    ]
+  },
   { "title": "OAuth clients", "path": "api-docs/oauth-clients" },
   { "title": "OAuth tokens", "path": "api-docs/oauth-tokens" },
   { "title": "Organizations", "path": "api-docs/organizations" },

content/terraform-docs-common/docs/cloud-docs/api-docs/changelog.mdx

@@ -9,6 +9,10 @@ description: >-
 
 Keep track of changes to the API for HCP Terraform and Terraform Enterprise.
 
+## 2026-04-2
+
+- The notifications API now includes endpoints for configuring project notifications. Refer to [Project notification configurations API reference](/terraform/cloud-docs/api-docs/notification-configurations/project) for more information.
+
 <!-- BEGIN: TFC:only name:stacks-tfe -->
 
 ## 2025-12-18

content/terraform-docs-common/docs/cloud-docs/api-docs/notification-configurations/index.mdx

@@ -0,0 +1,100 @@
+---
+page_title: Notification configurations API reference for HCP Terraform
+description: >-
+  Use the HCP Terraform API's notification configuration endpoints to manage notifications for workspaces, projects, and teams.
+tfc_only: true
+---
+
+[JSON API document]: /terraform/cloud-docs/api-docs#json-api-documents
+[JSON API error object]: https://jsonapi.org/format/#error-objects
+
+# Notification configurations API reference
+
+Use the notifications API endpoints for workspaces, projects, and teams to send notifications to external applications when a triggering event occurs. 
+
+## Notification types
+
+HCP Terraform supports the following types of notification configurations.
+
+### Workspace notification configurations
+
+Workspace notifications send alerts for run state transitions and workspace-specific events. Each workspace can have up to 20 notification configurations that apply to all runs for that workspace. Use workspace notifications to in the following cases:
+
+- Monitor run status changes
+- Track drift detection and continuous validation results
+- Receive alerts for health assessment failures
+- Get notified about automatic destroy runs
+
+Refer to [Workspace notification configurations API reference](/terraform/cloud-docs/api-docs/notification-configurations/workspace) for more information.
+
+### Project notification configurations
+
+Project notifications allow you to configure notifications for an entire project instead of setting them up for individual workspaces. These notifications automatically apply to every workspace in the project, making it easier to maintain consistent notification settings across multiple workspaces. Use project notifications to in the following cases:
+
+- Standardize notifications across all workspaces in a project
+- Reduce configuration overhead for large projects
+- Ensure consistent monitoring for related workspaces
+
+Refer to [Project notification configurations API reference](/terraform/cloud-docs/api-docs/notification-configurations/project) for more information.
+
+### Team notification configurations
+
+Team notifications send alerts to specific teams when relevant events occur. By default, every team has a default email notification configuration. If no users are assigned to a notification configuration, HCP Terraform sends email notifications to all team members. Use team notifications to in the following cases:
+
+- Notify teams about change requests for workspaces they can access
+- Route notifications to appropriate team channels
+- Manage team-specific alert preferences
+
+Refer to [Project notification configurations API reference](/terraform/cloud-docs/api-docs/notification-configurations/team)
+
+## Destination types
+
+All notification configurations support the following destination types:
+
+| Destination Type | Description |
+| --- | --- |
+| `generic` | Send JSON payloads to any HTTP/HTTPS endpoint. Supports HMAC authentication. |
+| `email` | Send email notifications to specified users or all members. |
+| `slack` | Send formatted messages to Slack channels using webhook URLs. |
+| `microsoft-teams` | Send formatted messages to Microsoft Teams channels using webhook URLs. |
+
+## Notification authenticity
+
+For `generic` destination types, HCP Terraform provides an HMAC signature on all notification requests using the configured `token` as the key. This signature is sent in the `X-TFE-Notification-Signature` header using the SHA-512 digest algorithm. Notification target servers should verify the source of HTTP requests by computing the HMAC of the request body using the same shared secret and dropping any requests with invalid signatures.
+
+Sample Ruby code for verifying the HMAC:
+
+```ruby
+token = SecureRandom.hex
+hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha512"), token, @request.body)
+fail "Invalid HMAC" if hmac != @request.headers["X-TFE-Notification-Signature"]
+```
+
+## Notification verification
+
+When saving a configuration with `enabled` set to `true`, or when using the verify API endpoint, HCP Terraform sends a verification request to the configured URL. The response to this request is stored and available in the `delivery-responses` array of the `notification-configuration` resource.
+
+HCP Terraform cannot enable configurations if the verification request fails. An HTTP response with a status code of `2xx` indicates success. You can only verify configurations with `destination_type` set to `email` manually, and they do not require an HTTP response.
+
+## Delivery responses
+
+Each delivery response contains several fields that provide information about the notification attempt:
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `body` | string | Response body (may be truncated). |
+| `code` | string | HTTP status code, e.g., `400`. |
+| `headers` | object | All HTTP headers received, represented as an object with keys for each header name (lowercased) and an array of string values. |
+| `sent-at` | date | The UTC timestamp when the notification was sent. |
+| `successful` | bool | Whether HCP Terraform considers this response to be successful. |
+| `url` | string | The URL to which the request was sent. |
+
+## Permissions
+
+You must have the following permissions to interact with the notifications API:
+
+- **Workspace notifications**: Admin access to the relevant workspace
+- **Project notifications**: Admin access to the relevant project
+- **Team notifications**: Appropriate team management permissions
+
+Refer to [HCP Terraform permissions documentation](/terraform/cloud-docs/users-teams-organizations/permissions) for more details.