Terraform Cloud can send notifications for run state transitions and workspace events. You can specify a destination URL, request type, and what events will trigger the notification. Each workspace can have up to 20 notification configurations, and they apply to all runs for that workspace.
Interacting with notification configurations requires admin access to the relevant workspace. (More about permissions.)
Notifications are sent as the run progresses, and can be triggered on one or more types of state transition. These are specified in the triggers array attribute. Available triggers are:
A plan has changes and Terraform requires user input to continue. This input may include approving the plan or a policy override.
Applying
"run:applying"
A run enters the Apply stage, where Terraform makes the infrastructure changes described in the plan.
Completed
"run:completed"
A run completes successfully.
Errored
"run:errored"
A run terminates early due to error or cancellation.
Drifted
"assessment:drifted"
Terraform Cloud detected configuration drift. This option is only available if you enabled drift detection for the workspace. Not available in Terraform Enterprise.
Health Assessment Failed
"assessment:failed"
A health assessment failed. This option is only available if you enable health assessments for the workspace. Not available in Terraform Enterprise.
The notification is an HTTP POST request with a detailed payload. The content depends on the type of notification.
For Slack and Microsoft Teams notifications, the payload conforms to the respective webhook API and results in a notification message with informational attachments. Refer to Slack Notification Payloads and Microsoft Teams Notification Payloads for examples. For generic notifications, the payload varies based on whether the notification contains information about run events or workspace events.
Run events include detailed information about a specific run, including the time it began and the associated workspace and organization. Generic notifications for run events contain the following information:
Name
Type
Description
payload_version
number
Always "1".
notification_configuration_id
string
The ID of the configuration associated with this notification.
run_url
string
URL used to access the run UI page.
run_id
string
ID of the run which triggered this notification.
run_message
string
The reason the run was queued.
run_created_at
string
Timestamp of the run's creation.
run_created_by
string
Username of the user who created the run.
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.
notifications
array
List of events which caused this notification to be sent, with each event represented by an object. At present, this is always one event, but in the future Terraform Cloud may roll up several notifications for a run into a single request.
notifications[].message
string
Human-readable reason for the notification.
notifications[].trigger
string
Value of the trigger which caused the notification to be sent.
notifications[].run_status
string
Status of the run at the time of notification.
notifications[].run_updated_at
string
Timestamp of the run's update.
notifications[].run_updated_by
string
Username of the user who caused the run to update.
{"payload_version":1,"notification_configuration_id":"nc-AeUQ2zfKZzW9TiGZ","run_url":"https://app.terraform.io/app/acme-org/my-workspace/runs/run-FwnENkvDnrpyFC7M","run_id":"run-FwnENkvDnrpyFC7M","run_message":"Add five new queue workers","run_created_at":"2019-01-25T18:34:00.000Z","run_created_by":"sample-user","workspace_id":"ws-XdeUVMWShTesDMME","workspace_name":"my-workspace","organization_name":"acme-org","notifications":[{"message":"Run Canceled","trigger":"run:errored","run_status":"canceled","run_updated_at":"2019-01-25T18:37:04.000Z","run_updated_by":"sample-user"}]}
{"payload_version":1,"notification_configuration_id":"nc-AeUQ2zfKZzW9TiGZ","run_url":"https://app.terraform.io/app/acme-org/my-workspace/runs/run-FwnENkvDnrpyFC7M","run_id":"run-FwnENkvDnrpyFC7M","run_message":"Add five new queue workers","run_created_at":"2019-01-25T18:34:00.000Z","run_created_by":"sample-user","workspace_id":"ws-XdeUVMWShTesDMME","workspace_name":"my-workspace","organization_name":"acme-org","notifications":[{"message":"Run Canceled","trigger":"run:errored","run_status":"canceled","run_updated_at":"2019-01-25T18:37:04.000Z","run_updated_by":"sample-user"}]}
Workspace events include detailed information about workspace-level validation events like health assessments if you enable them for the workspace. Much of the information provides details about the associated assessment result, which Terraform Cloud uses to track instances of continuous validation. Generic notifications for workspace events contain the following information:
Name
Type
Description
payload_version
number
Always "2".
notification_configuration_id
string
The ID of the configuration associated with this notification.
notification_configuration_url
string
URL to get the notification configuration from the Terraform Cloud API.
trigger_scope
string
Always "assessment" for workspace notifications.
trigger
string
Value of the trigger that caused the notification to be sent.
message
string
Human-readable reason for the notification.
details
object
Object containing details specific to the notification.
details.new_assessment_result
object
The most recent assessment result. This result triggered the notification.
details.new_assessment_result.id
string
ID of the assessment result.
details.new_assessment_result.url
string
URL to get the assessment result from the Terraform Cloud API.
details.new_assessment_result.succeeded
bool
Whether or not assessment succeeded.
details.new_assessment_result.drifted
bool
Whether or not assessment detected drift.
details.new_assessment_result.created_at
string
Timestamp of the assessment result
details.prior_assessment_result
object
The assessment result immediately prior to the one that triggered the notification.
details.prior_assessment_result.id
string
ID of the assessment result.
details.prior_assessment_result.url
string
URL to get the assessment result from the Terraform Cloud API.
details.prior_assessment_result.succeeded
bool
Whether or not assessment succeeded.
details.prior_assessment_result.drifted
bool
Whether or not assessment detected drift.
details.prior_assessment_result.created_at
string
Timestamp of the assessment result.
details.workspace_id
string
ID of the workspace that generated the notification.
If a token is configured, Terraform Cloud 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.
When saving a configuration with enabled set to true, or when using the verify API, Terraform Cloud 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_typeemail 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 or not Terraform Cloud considers this response to be successful.
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, a verification request will be sent before saving the configuration. If this request receives no response or the response is not successful (HTTP 2xx), the configuration will not save.
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.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":["run:applying","run:completed","run:created","run:errored","run:needs_attention","run:planning"]}}}
{"data":{"type":"notification-configuration","attributes":{"destination-type":"generic","enabled":true,"name":"Webhook server test","url":"https://httpstat.us/200","triggers":["run:applying","run:completed","run:created","run:errored","run:needs_attention","run:planning"]}}}
»Sample Payload for Email Notification Configurations
{"data":{"type":"notification-configurations","attributes":{"destination-type":"email","enabled":true,"name":"Notify organization users about run","triggers":["run:applying","run:completed","run:created","run:errored","run:needs_attention","run:planning"]},"relationships":{"users":{"data":[{"id":"organization-user-id","type":"users"}]}}}}
{"data":{"type":"notification-configurations","attributes":{"destination-type":"email","enabled":true,"name":"Notify organization users about run","triggers":["run:applying","run:completed","run:created","run:errored","run:needs_attention","run:planning"]},"relationships":{"users":{"data":[{"id":"organization-user-id","type":"users"}]}}}}
GET /workspaces/:workspace_id/notification-configurations
Parameter
Description
:workspace_id
The ID of the workspace to list configurations from. Obtain this from the workspace settings or the Show Workspace endpoint. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results.
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.
The id of the notification configuration to update.
If the enabled attribute is true, updating the configuration will cause Terraform Cloud to send a verification request. If a response is received, it will be stored and returned in the delivery-responses attribute. More details in the Notification Verification and Delivery Responses section above.
This PATCH endpoint requires a JSON object with the following properties as a request payload.
If enabled is set to true, a verification request will be sent before saving the configuration. If this request fails to send, or the response is not successful (HTTP 2xx), the configuration will not save.
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, which can be used at the receiving server to verify request authenticity. See Notification Authenticity for more details.
data.attributes.triggers
array
(previous value)
Array of triggers for sending notifications. See Notification Triggers for more details.
data.attributes.url
string
(previous value)
HTTP or HTTPS URL to which notification requests will be made, only for configurations with "destination_type:""slack", "microsoft-teams" or "generic"
data.relationships.users
array
Array of users part of the organization, only for configurations with "destination_type:""email"
POST /notification-configurations/:notification-configuration-id/actions/verify
Parameter
Description
:notification-configuration-id
The id of the notification configuration to verify.
This will cause Terraform Cloud to send a verification request for the specified configuration. If a response is received, it will be stored and returned in the delivery-responses attribute. More details in the Notification Verification and Delivery Responses section above.
