HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Project notifications

HCP Terraform sends webhooks and emails to notify external systems about workspace run events. You can configure notifications for an entire project instead of setting them up for individual workspaces. Project notifications apply to every workspace in the project. This lets you create standard alerts, such as a PagerDuty webhook for production errors, without configuring each new workspace.

Refer to Project notification configurations API reference for information on how to create and manage notifications using the API.

Overview

Project notifications work alongside workspace notifications and exhibit the following behaviors:

  • Project notifications trigger for all current workspaces in the project unless you exclude them from a notification configuration. They also trigger for any workspaces that you create in the project or move into it later, unless you add those workspaces to the exclusion list.
  • 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.
  • Workspace administrators cannot turn off project notifications from workspace settings. You must either modify or exclude workspaces from project. Alternatively, you can move the workspace to another project.
  • You can exclude specific workspaces from a project notification configuration. Workspaces that have been exluded do send notifications for that configuration. Use exclusions when you want to keep project-level notifications for critical workspaces but omit low-priority development or test workspaces.

Requirements

You must have project admin permissions to create and manage project notifications. Refer to Project permissions for details.

During the private beta, email destinations must belong to registered HCP Terraform users in your organization.

Create a project notification

A notification configuration requires a destination, a payload type, the events that should generate a notification, and optional workspace exclusions.

  1. Sign in to HCP Terraform or Terraform Enterprise and open the project you want to configure.

  2. Click Settings, then Notifications.

  3. Click Create a notification.

  4. Choose a destination type.

  5. Enter a display name for the notification.

  6. Configure the destination:

    • Webhook: To send messages to a generic webhook, enter the destination URL. The URL must accept HTTP or HTTPS POST requests. you can optionally enter a token. HCP Terraform uses this secret string to sign webhooks so you can verify their source.
    • Email: To send messages to an email address, choose recipients from the drop-down menu.
    • Slack: To send messages to a Slack channel, enter the Slack webhook URL.
    • Microsoft Teams: To send messages to a Teams channel, specify the webhook URL for the channel.

  7. HCP Terraform sends notifications when the specified event occurs in any workspace in the project, but you can specify additional workspaces in the organization that also trigger the notification.

  8. Select which workspace events trigger the notification. You can choose all events, no events, or Only certain events to enable specific workspace event types, such as when checks fail.

  9. Select which run events trigger the notification. You can choose all events, no events, or Only certain events to enable specific run event types, such as when a run completes or errors.

  10. Optional: Exclude workspaces that should not use this notification configuration. Search for workspaces in the project and add them to the exclusion list.

  11. Click Create notification configuration.

After you create the notification, the confirmation screen lets you perform the following actions:

  • Send a test notification.
  • Disable the notification by toggling the Enabled slider. Refer to Enable and verify notifications for details.
  • Delete the notification.
  • Edit the notification.

Enable and verify notifications

To enable or disable a notification, open the notification page and toggle the Enabled or Disabled slider.

Before HCP Terraform enables a generic or Slack webhook, it sends a test message to the URL. The destination must return a 2xx HTTP status code. If the test fails, HCP Terraform displays an error and leaves the notification disabled. You must fix the connection before you can enable the notification.

Notification payloads

Project notifications use the same payload formats as workspace notifications. Refer to Workspace notifications for payload details and examples.

For generic notifications, the complete payload schema is documented in the project notification configurations API reference.

Notification authenticity

Slack notifications use Slack's own protocols for verifying HCP Terraform webhook requests.

Generic notifications can include a signature for verifying the request. If a project notification configuration includes a secret token, HCP Terraform includes an X-TFE-Notification-Signature header containing an HMAC signature computed from that token using the SHA-512 digest algorithm. The receiving service is responsible for validating the signature. Refer to Notification authenticity for details and an example.

Edit this page on GitHub