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 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 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

Destination types

All notification configurations support the following destination types:

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:

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:

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 for more details.