Team notification configurations API reference

Use the team notifications API endpoints to configure relevant alerts that notify teams you specify whenever a supported event occurs.

Note: Notifications are available in the HCP Terraform Standard and Premium editions. Refer to HCP Terraform pricing for details.

Overview

By default, every team has a default email notification configuration with no users assigned. If a notification configuration has no users assigned, HCP Terraform sends email notifications to all team members. The following table lists the available API endpoints for managing team notification configurations:

Method	Endpoint	Description
`POST`	`/teams/:team_id/notification-configurations`	Create a new notification configuration for a team
`GET`	`/teams/:team_id/notification-configurations`	List all notification configurations for a team
`GET`	`/notification-configurations/:notification-configuration-id`	Retrieve details of a specific notification configuration
`PATCH`	`/notification-configurations/:notification-configuration-id`	Update an existing notification configuration
`POST`	`/notification-configurations/:notification-configuration-id/actions/verify`	Send a verification request to test a notification configuration
`DELETE`	`/notification-configurations/:notification-configuration-id`	Delete a notification configuration

For workspace notification configurations, refer to Workspace notification configurations API reference. For project notification configurations, refer to Project notification configurations API reference.

Notification triggers

The following trigger is available for team notifications.

Display name	Value	Description
Change request created	`"change_request:created"`	HCP Terraform sends a notification when someone creates a change request for a workspace that the specified team can access.

Notification payload

Team notification configurations use a change request payload for generic notifications.

Change request notification payload

Change request events contain the following fields in their payloads.

Name	Type	Description
`payload_version`	number	Always "1".
`notification_configuration_id`	string	The ID of the configuration associated with this notification.
`change_request_url`	string	URL used to access the change request UI page.
`change_request_subject`	string	Title of the change request which triggered this notification.
`change_request_message`	string	The contents of the change request.
`change_request_created_at`	string	Timestamp of the change request's creation.
`change_request_created_by`	string	Username of the user who created the change request.
`workspace_id`	string	ID of the run's workspace.
`workspace_name`	string	Human-readable name of the run's workspace.
`organization_name`	string	Human-readable name of the run's organization.

`Send a test` payload

This is a sample payload you can send to test if notifications are working. The payload does not have a run or workspace context, resulting in null values.

{
  "payload_version": 1,
  "notification_configuration_id": "nc-jWvVsmp5VxsaCeXm",
  "run_url": null,
  "run_id": null,
  "run_message": null,
  "run_created_at": null,
  "run_created_by": null,
  "workspace_id": null,
  "workspace_name": null,
  "organization_name": null,
  "notifications": [
    {
      "message": "Verification of test",
      "trigger": "verification",
      "run_status": null,
      "run_updated_at": null,
      "run_updated_by": null
    }
  ]
}

Notification authenticity

If a token is configured, HCP Terraform provides an HMAC signature on all "generic" notification requests, using the token as the key. This is sent in the X-TFE-Notification-Signature header. The digest algorithm used is SHA-512. Notification target servers should verify the source of the HTTP request 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 and delivery responses

When saving a configuration with enabled set to true, or when using the verify API, 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.

Configurations cannot be enabled if the verification request fails. Success is defined as an HTTP response with status code of 2xx. Configurations with destination_type email can only be verified manually, they do not require an HTTP response.

The most recent response is stored in the delivery-responses array.

Each delivery response has several fields:

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 (most arrays will be size one).
`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.

Create a team notification configuration

Use this endpoint to create a notification configuration to notify a team.

POST /teams/:team_id/notification-configurations

Parameter	Description
`:team_id`	The ID of the team to create a configuration for.

Status	Response	Reason
201	JSON API document (`type: "notification-configurations"`)	Successfully created a notification configuration
400	JSON API error object	Unable to complete verification request to destination URL
404	JSON API error object	Team not found, or user unauthorized to perform action
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Request body

This POST endpoint requires a JSON object with the following properties as a request payload. Properties without a default value are required.

If enabled is set to true, HCP Terraform sends a verification request before saving the configuration. If this request does not receive a response or the response is not successful (HTTP 2xx), the configuration will not be saved.

Key path	Type	Default	Description
`data.type`	string		Must be `"notification-configuration"`.
`data.attributes.destination-type`	string		Type of notification payload to send. Valid values are `"generic"`, `"email"`, `"slack"` or `"microsoft-teams"`.
`data.attributes.enabled`	bool	`false`	Disabled configurations will not send any notifications.
`data.attributes.name`	string		Human-readable name for the configuration.
`data.attributes.token`	string or null	`null`	Optional write-only secure token, which can be used at the receiving server to verify request authenticity. See Notification Authenticity for more details.
`data.attributes.triggers`	array	`[]`	Array of triggers for which this configuration will send notifications. See Notification Triggers for more details and a list of allowed values.
`data.attributes.url`	string		HTTP or HTTPS URL to which notification requests will be made, only for configurations with `"destination_type:"` `"slack"`, `"microsoft-teams"` or `"generic"`
`data.attributes.email_all_members`	bool		Email all team members, only for configurations with `"destination_type:" "email"`.
`data.relationships.users`	array		Array of users part of the organization, only for configurations with `"destination_type:"` `"email"`

Sample payload for generic notification configurations

{
  "data": {
    "type": "notification-configuration",
    "attributes": {
      "destination-type": "generic",
      "enabled": true,
      "name": "Webhook server test",
      "url": "https://httpstat.us/200",
      "triggers": [
        "change_request:created"
      ]
    }
  }
}

Sample payload for email notification configurations

{
  "data": {
    "type": "notification-configurations",
    "attributes": {
      "destination-type": "email",
      "enabled": true,
      "name": "Email teams about change requests",
      "triggers": [
        "change_request:created"
      ]
    },
    "relationships": {
      "users": {
        "data": [{ "id": "organization-user-id", "type": "users" }]
      }
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC/notification-configurations

Sample response

{
  "data": {
    "id": "nc-AeUQ2zfKZzW9TiGZ",
    "type": "notification-configurations",
    "attributes": {
      "enabled": true,
      "name": "Webhook server test",
      "url": "https://httpstat.us/200",
      "destination-type": "generic",
      "token": null,
      "triggers": [
        "change_request:created"
      ],
      "delivery-responses": [
        {
          "url": "https://httpstat.us/200",
          "body": "\"200 OK\"",
          "code": "200",
          "headers": {
            "cache-control": ["private"],
            "content-length": ["129"],
            "content-type": ["application/json; charset=utf-8"],
            "content-encoding": ["gzip"],
            "vary": ["Accept-Encoding"],
            "server": ["Microsoft-IIS/10.0"],
            "x-aspnetmvc-version": ["5.1"],
            "access-control-allow-origin": ["*"],
            "x-aspnet-version": ["4.0.30319"],
            "x-powered-by": ["ASP.NET"],
            "set-cookie": ["ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us"],
            "date": ["Tue, 08 Jan 2024 21:34:37 GMT"]
          },
          "sent-at": "2024-01-08 21:34:37 UTC",
          "successful": "true"
        }
      ],
      "created-at": "2024-01-08T21:32:14.125Z",
      "updated-at": "2024-01-08T21:34:37.274Z"
    },
    "relationships": {
      "subscribable": {
        "data": {
          "id": "team-6p5jTwJQXwqZBncC",
          "type": "teams"
        }
      }
    },
    "links": {
      "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ"
    }
  }
}

List team notification configurations

Use this endpoint to list notification configurations for a team.

GET /teams/:team_id/notification-configurations

Parameter	Description
`:team_id`	The ID of the teams to list configurations from.

Query parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 notification configurations per page.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/teams/team-6p5jTwJQXwqZBncC/notification-configurations

Sample response

{
  "data": [
    {
      "id": "nc-W6VGEi8A7Cfoaf4K",
      "type": "notification-configurations",
      "attributes": {
        "enabled": false,
        "name": "Slack: #devops",
        "url": "https://hooks.slack.com/services/T00000000/BC012345/0PWCpQmYyD4bTTRYZ53q4w",
        "destination-type": "slack",
        "token": null,
        "triggers": [
          "change_request:created"
        ],
        "delivery-responses": [],
        "created-at": "2019-01-08T21:34:28.367Z",
        "updated-at": "2019-01-08T21:34:28.367Z"
      },
      "relationships": {
        "subscribable": {
          "data": {
            "id": "team-TdeUVMWShTesDMME",
            "type": "teams"
          }
        }
      },
      "links": {
        "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K"
      }
    },
    {
      "id": "nc-AeUQ2zfKZzW9TiGZ",
      "type": "notification-configurations",
      "attributes": {
        "enabled": true,
        "name": "Webhook server test",
        "url": "https://httpstat.us/200",
        "destination-type": "generic",
        "token": null,
        "triggers": [
          "change_request:created"
        ],
        "delivery-responses": [
          {
            "url": "https://httpstat.us/200",
            "body": "\"200 OK\"",
            "code": "200",
            "headers": {
              "cache-control": ["private"],
              "content-length": ["129"],
              "content-type": ["application/json; charset=utf-8"],
              "content-encoding": ["gzip"],
              "vary": ["Accept-Encoding"],
              "server": ["Microsoft-IIS/10.0"],
              "x-aspnetmvc-version": ["5.1"],
              "access-control-allow-origin": ["*"],
              "x-aspnet-version": ["4.0.30319"],
              "x-powered-by": ["ASP.NET"],
              "set-cookie": ["ARRAffinity=77c477e3e649643e5771873e1a13179fb00983bc73c71e196bf25967fd453df9;Path=/;HttpOnly;Domain=httpstat.us"],
              "date": ["Tue, 08 Jan 2019 21:34:37 GMT"]
            },
            "sent-at": "2019-01-08 21:34:37 UTC",
            "successful": "true"
          }
        ],
        "created-at": "2019-01-08T21:32:14.125Z",
        "updated-at": "2019-01-08T21:34:37.274Z"
      },
      "relationships": {
        "subscribable": {
          "data": {
            "id": "team-XdeUVMWShTesDMME",
            "type": "teams"
          }
        }
      },
      "links": {
        "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ"
      }
    }
  ]
}

Show a team notification configuration

GET /notification-configurations/:notification-configuration-id

Use this endpoint to read an existing team notification configuration after you know its notification configuration ID.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ

Successful responses return a JSON API document with type: "notification-configurations". In the response, relationships.subscribable.data references the team with type: "teams".

Update a team notification configuration

PATCH /notification-configurations/:notification-configuration-id

If the enabled attribute is true, updating the configuration causes HCP Terraform to send a verification request. If a response is received, it is stored and returned in the delivery-responses attribute.

Request body

Key path	Type	Default	Description
`data.type`	string	(previous value)	Must be `"notification-configuration"`.
`data.attributes.enabled`	bool	(previous value)	Disabled configurations will not send any notifications.
`data.attributes.name`	string	(previous value)	User-readable name for the configuration.
`data.attributes.token`	string	(previous value)	Optional write-only secure token.
`data.attributes.triggers`	array	(previous value)	Array of triggers for sending notifications.
`data.attributes.url`	string	(previous value)	HTTP or HTTPS URL to which notification requests will be made for `generic`, `slack`, or `microsoft-teams` destinations.
`data.relationships.users`	array		Array of users in the organization, only for configurations with `"destination_type:"` `"email"`.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ

Successful responses return a JSON API document with type: "notification-configurations" and relationships.subscribable.data.type set to "teams".

Verify a team notification configuration

POST /notification-configurations/:notification-configuration-id/actions/verify

This causes HCP Terraform to send a verification request for the specified configuration.

Status	Response	Reason
200	JSON API document (`type: "notification-configurations"`)	Successfully verified the notification configuration
400	JSON API error object	Unable to complete verification request to destination URL

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ/actions/verify

Delete a team notification configuration

DELETE /notification-configurations/:notification-configuration-id

Status	Response	Reason
204	None	Successfully deleted the notification configuration
404	JSON API error object	Notification configuration not found, or user unauthorized to perform action

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ

Team notification configurations API reference

Overview

Notification triggers

Notification payload

Change request notification payload

Send a test payload

Notification authenticity

Notification verification and delivery responses

Create a team notification configuration

Request body

Sample payload for generic notification configurations

Sample payload for email notification configurations

Sample request

Sample response

List team notification configurations

Query parameters

Sample request

Sample response

Show a team notification configuration

Sample request

Update a team notification configuration

Request body

Sample request

Verify a team notification configuration

Sample request

Delete a team notification configuration

Sample request

`Send a test` payload