Manage team notifications

HCP Terraform can use webhooks to notify external systems about run progress, change requests, and other events. Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs.

You can configure an individual team notification to notify up to twenty teams. To set up notifications for teams using the API, refer to the Notification API.

Requirements

To configure team notifications, you need the Manage teams permissions for the team for which you want to configure notifications.

View notification configuration settings

To view your current team notifications, perform the following steps:

1. Navigate to your organization’s Settings page.
2. Select Teams in the sidebar navigation.
3. Select the team for which you want to view the notifications from your list of teams.
4. Select Notifications in the sidebar navigation.

HCP Terraform displays a list of any notification configurations you have set up. A notification configuration defines how and when you want to send notifications, and once you enable that configuration, it can send notifications.

Update and enable notification configurations

Each notification configuration includes a brief overview of each configuration’s name, type, the events that can trigger the notification, and the last time the notification was triggered. Clicking on a notification configuration opens a page where you can perform the following actions:

• Enable your configuration to send notifications by toggling the switch.
• Delete a configuration by clicking Delete notification, then Yes, delete notification configuration.
• Test your notification’s configuration by clicking Send test.
• Click Edit notification to edit your notification configuration.

After creating a notification configuration, you can only edit the following aspects of that configuration:

1. The configuration’s name.
2. Whether this configuration notifies everyone on a team or specific members.
3. The workspace events that trigger notifications. You can choose from:
   • All events triggers a notification for every event in your workspace.
   • No events means that no workspace events trigger a notification.
   • Only certain events lets you specify which events trigger a notification.

After making any changes, click Update notification to save your changes.

Create and configure a notification

To configure a new notification for a team or a user, perform the following steps:

1. Navigate to your organization’s Settings page.
2. Select Teams in the sidebar navigation.
3. Select the team you want to view the notifications for from your list of teams.
4. Select Notifications in the sidebar navigation.
5. Click Create a notification.

You must complete the following fields for all new notification configurations:

1. The Destination where HCP Terraform should deliver either a generic or a specifically formatted payload. Refer to Notification payloads for details.
2. The display Name for this notification configuration.
3. If you configure an email notification, you can optionally specify which Email Recipients will receive this notification.
4. If you choose to configure a webhook, you must also specify:
   • A Webhook URL for the destination of your webhook payload. Your URL must accept HTTP or HTTPS POST requests and be able to use the chosen payload type.
   • You can optionally configure a Token as an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to Notification authenticity for details. You cannot view the token after you save the notification configuration.
5. If you choose to specify either a Slack or Microsoft Teams notification, you must also configure your webhook URL for either service. For details, refer to Slack's documentation on creating an incoming webhook and Microsoft's documentation on creating a workflow from a channel in teams.
6. Specify which Workspace events should trigger this notification.
7. After you finish configuring your notification, click Create a notification.

Note that if you are create an email notification, you must have Manage membership permissions on a team to select users from that team as email recipients.

Workspace events

HCP Terraform can send notifications for all workspace events, no workspace events, or specific events. The following events are available for you to specify:

Enable and verify a notification

To configure HCP Terraform to stop sending notifications for a notification configuration, disable the Enabled setting on a configuration's detail page .

HCP Terraform enables notifications for email configurations by default. Before enabling any webhook notifications, HCP Terraform attempts to verify the notification’s configuration by sending a test message. If the test succeeds, HCP Terraform enables the notification.

To verify a notification configuration, the destination must respond with a 2xx HTTP code. If verification fails, HCP Terraform does not enable the configuration and displays an error message.

For successful and unsuccessful verifications, click the Last Response box to view more information about the verification results. You can also send additional test messages by clicking Send a Test.

Notification Payloads

Notification payloads contain different attributes depending on the integration you specified when configuring that notification.

Slack

Notifications to Slack contain the following information:

• Information about the change request, including the username and avatar of the person who created the change request.
• The event that triggered the notification and the time that event occurred.

Microsoft Teams

Notifications to Microsoft Teams contain the following information:

• Information about the change request, including the username and avatar of the person who created the change request.
• The event that triggered the notification and the time that event occurred.

Email

Email notifications contain the following information:

• Information about the change request, including the username and avatar of the person who created the change request.
• The event that triggered the notification and the time that event occurred.

Generic

A generic notification contains information about the event that triggered it and the time that the event occurred. You can refer to the complete generic notification payload in the API documentation.

You can use some of the values in the payload to retrieve additional information through the API, such as:

• The workspace ID
• The organization name

Notification Authenticity

Slack notifications use Slack's own protocols to verify HCP Terraform's webhook requests.

Generic notifications can include a signature to verify the request. For notification configurations that include a secret token, HCP Terraform's webhook requests include an X-TFE-Notification-Signature header containing an HMAC signature computed from the token using the SHA-512 digest algorithm. The notification’s receiving service is responsible for validating the signature. For more information and an example of how to validate the signature, refer to the API documentation.