Notification Configurations API
HCP Terraform 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.)
Note:Speculative plans and workspaces configured withLocalexecution mode do not support notifications.
Notification Triggers
Notifications are sent as the run progresses, and can be triggered on one or more types of state transition. These are specified in thetriggers array attribute. Available triggers are:
| Display Name | Value | Description |
|---|---|---|
| Created | "run:created" | A run is created and enters thePending stage |
| Planning | "run:planning" | A run acquires the lock and starts to execute. |
| Needs Attention | "run:needs_attention" | A plan has changes and Terraform requires user input to continue. This input may include approving the plan or apolicy override. |
| Applying | "run:applying" | A run enters theApply 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" | HCP Terraform detected configuration drift. This option is only available if you enabled drift detection for the workspace. |
| Checks Failed | "assessment:check_failure" | One or more continuous validation checks did not pass. This option is only available if you enabled drift detection for the workspace. |
| Health Assessment Failed | "assessment:failed" | A health assessment failed. This option is only available if you enable health assessments for the workspace. |
| Auto Destroy Reminder | "workspace:auto_destro_reminder" | An automated workspace destroy run is imminent. |
| Auto Destroy Results | "workspace:auto_destroy_run_results" | HCP Terraform attempted an automated workspace destroy run. |
Notification Payload
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 toSlack Notification Payloads andMicrosoft 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 Notification Payload
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 HCP Terraform 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. |
Sample Payload
{ "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" } ]}Send a test Payload
This is a sample payload you can send to test if notifications are working. The payload does not have arun orworkspace context, resulting in null values.
You can trigger a test notification from the workspace notifcation settings page. You can read more about verifying anotificaton configuration.
{ "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, } ]}Workspace Notification Payload
Workspace events include detailed information about workspace-level validation events likehealth assessments if you enable them for the workspace. Much of the information provides details about the associatedassessment result, which HCP Terraform uses to track instances of continuous validation.
HCP Terraform returns different types of attributes returned in the payload details, depending on the type oftrigger_scope. There are two main values fortrigger_scope:assessment andworkspace, examples of which you can see below.
Health Assessments
Health assessment 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 HCP Terraform API. |
trigger_scope | string | Always "assessment" for workspace assessment 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 HCP Terraform API. |
details.new_assessment_result.succeeded | bool | Whether assessment succeeded. |
details.new_assessment_result.all_checks_succeeded | bool | Whether all conditions passed. |
details.new_assessment_result.checks_passed | number | The number of resources, data sources, and outputs passing their conditions. |
details.new_assessment_result.checks_failed | number | The number of resources, data sources, and outputs with one or more failing conditions. |
details.new_assessment_result.checks_errored | number | The number of resources, data sources, and outputs that had a condition error. |
details.new_assessment_result.checks_unknown | number | The number of resources, data sources, and outputs that had conditions left unevaluated. |
details.new_assessment_result.drifted | bool | Whether assessment detected drift. |
details.new_assessment_result.resources_drifted | number | The number of resources whose configuration does not match from the workspace's state file. |
details.new_assessment_result.resources_undrifted | number | The number of real resources whose configuration matches the workspace's state file. |
details.new_assessment_result.created_at | string | Timestamp for when HCP Terraform created 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 HCP Terraform API. |
details.prior_assessment_result.succeeded | bool | Whether assessment succeeded. |
details.prior_assessment_result.all_checks_succeeded | bool | Whether all conditions passed. |
details.prior_assessment_result.checks_passed | number | The number of resources, data sources, and outputs passing their conditions. |
details.prior_assessment_result.checks_failed | number | The number of resources, data sources, and outputs with one or more failing conditions. |
details.prior_assessment_result.checks_errored | number | The number of resources, data sources, and outputs that had a condition error. |
details.prior_assessment_result.checks_unknown | number | The number of resources, data sources, and outputs that had conditions left unevaluated. |
details.prior_assessment_result.drifted | bool | Whether assessment detected drift. |
details.prior_assessment_result.resources_drifted | number | The number of resources whose configuration does not match the workspace's state file. |
details.prior_assessment_result.resources_undrifted | number | The number of resources whose configuration matches the workspace's state file. |
details.prior_assessment_result.created_at | string | Timestamp of the assessment result. |
details.workspace_id | string | ID of the workspace that generated the notification. |
details.workspace_name | string | Human-readable name of the workspace. |
details.organization_name | string | Human-readable name of the organization. |
Sample Payload
Health assessment payloads have information about resource drift and continuous validation checks.
{ "payload_version": "2", "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", "trigger_scope": "assessment", "trigger": "assessment:drifted", "message": "Drift Detected", "details": { "new_assessment_result": { "id": "asmtres-vRVQxpqq64EA9V5a", "url": "https://app.terraform.io/api/v2/assessment-results/asmtres-vRVQxpqq64EA9V5a", "succeeded": true, "drifted": true, "all_checks_succeeded": true, "resources_drifted": 4, "resources_undrifted": 55, "checks_passed": 33, "checks_failed": 0, "checks_errored": 0, "checks_unknown": 0, "created_at": "2022-06-09T05:23:10Z" }, "prior_assessment_result": { "id": "asmtres-A6zEbpGArqP74fdL", "url": "https://app.terraform.io/api/v2/assessment-results/asmtres-A6zEbpGArqP74fdL", "succeeded": true, "drifted": true, "all_checks_succeeded": true, "resources_drifted": 4, "resources_undrifted": 55, "checks_passed": 33, "checks_failed": 0, "checks_errored": 0, "checks_unknown": 0, "created_at": "2022-06-09T05:22:51Z" }, "workspace_id": "ws-XdeUVMWShTesDMME", "workspace_name": "my-workspace", "organization_name": "acme-org" }}Automatic Destroy Runs
Automatic destroy run notifications for workspace events contain the following information:
| Name | Type | Description |
|---|---|---|
payload_version | string | Always 2. |
notification_configuration_id | string | The ID of the notification's configuration. |
notification_configuration_url | string | The URL to get the notification's configuration from the HCP Terraform API. |
trigger_scope | string | Always "workspace" for ephemeral workspace notifications |
trigger | string | Value of the trigger that caused HCP Terraform to send the notification. |
message | string | Human-readable reason for the notification. |
details | object | Object containing details specific to the notification. |
details.auto_destroy_at | string | Timestamp when HCP Terraform will schedule the next destroy run. Only applies to reminder notifications. |
details.run_created_at | string | Timestamp of when HCP Terraform successfully created a destroy run. Only applies to results notifications. |
details.run_status | string | Status of the scheduled destroy run. Only applies to results notifications. |
details.run_external_id | string | The ID of the scheduled destroy run. Only applies to results notifications. |
details.run_create_error_message | string | Message detailing why the run was unable to be queued. Only applies to results notifications. |
details.trigger_type | string | The type of notification, and the value is either "reminder" or "results". |
details.workspace_name | string | Human-readable name of the workspace. |
details.organization_name | string | Human-readable name of the organization. |
Sample Payload
The shape of data in auto destroy notification payloads may differ depending on the success of the run HCP Terraform created. Refer to the specific examples below.
Reminder
Reminders that HCP Terraform will trigger a destroy run at some point in the future.
{ "payload_version": "2", "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", "trigger_scope": "workspace", "trigger": "workspace:auto_destroy_reminder", "message": "Auto Destroy Reminder", "details": { "auto_destroy_at": "2025-01-01T00:00:00Z", "run_created_at": null, "run_status": null, "run_external_id": null, "run_create_error_message": null, "trigger_type": "reminder", "workspace_name": "learned-english-dog", "organization_name": "acme-org" }}Results
The final result of the scheduled auto destroy run includes additional metadata about the run.
{ "payload_version": "2", "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", "trigger_scope": "workspace", "trigger": "workspace:auto_destroy_results", "message": "Auto Destroy Results", "details": { "auto_destroy_at": null, "run_created_at": "2022-06-09T05:22:51Z", "run_status": "applied", "run_external_id": "run-vRVQxpqq64EA9V5a", "run_create_error_message": null, "trigger_type": "results", "workspace_name": "learned-english-dog", "organization_name": "acme-org" }}Failed Run Creation
Run-specific values are empty when HCP Terraform was unable to create an auto destroy run.
{ "payload_version": "2", "notification_configuration_id": "nc-SZ3V3cLFxK6sqLKn", "notification_configuration_url": "https://app.terraform.io/api/v2/notification-configurations/nc-SZ3V3cLFxK6sqLKn", "trigger_scope": "workspace", "trigger": "workspace:auto_destroy_results", "message": "Auto Destroy Results", "details": { "auto_destroy_at": null, "run_created_at": null, "run_status": null, "run_external_id": null, "run_create_error_message": "Configuration version is missing", "trigger_type": "results", "workspace_name": "learned-english-dog", "organization_name": "acme-org" }}Notification Authenticity
If atoken is configured, HCP Terraform provides an HMAC signature on all"generic" notification requests, using thetoken as the key. This is sent in theX-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.hexhmac= 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 withenabled set totrue, or when using theverify API, HCP Terraform sends a verification request to the configured URL. The response to this request is stored and available in thedelivery-responses array of thenotification-configuration resource.
Configurations cannot be enabled if the verification request fails. Success is defined as an HTTP response with status code of2xx.Configurations withdestination_typeemail can only be verified manually, they do not require an HTTP response.
The most recent response is stored in thedelivery-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 Notification Configuration
POST /workspaces/:workspace_id/notification-configurations
| Parameter | Description |
|---|---|
:workspace_id | The ID of the workspace to list configurations for. Obtain this from theworkspace settings or theShow Workspace endpoint. |
| 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 | Workspace 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.
Ifenabled is set totrue, 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. SeeNotification Authenticity for more details. |
data.attributes.triggers | array | [] | Array of triggers for which this configuration will send notifications. SeeNotification 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" ] } }}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" } ] } } }}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/workspaces/ws-XdeUVMWShTesDMME/notification-configurationsSample 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": [ "run:applying", "run:completed", "run:created", "run:errored", "run:needs_attention", "run:planning" ], "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": "ws-XdeUVMWShTesDMME", "type": "workspaces" } } }, "links": { "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" } }}List Notification Configurations
GET /workspaces/:workspace_id/notification-configurations
| Parameter | Description |
|---|---|
:workspace_id | The ID of the workspace to list configurations from. Obtain this from theworkspace settings or theShow Workspace endpoint. If neither pagination query parameters are provided, the endpoint will not be paginated and will return all results. |
Query Parameters
This endpoint supports paginationwith 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/workspaces/ws-XdeUVMWShTesDMME/notification-configurationsSample 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": [ "run:errored", "run:needs_attention" ], "delivery-responses": [], "created-at": "2019-01-08T21:34:28.367Z", "updated-at": "2019-01-08T21:34:28.367Z" }, "relationships": { "subscribable": { "data": { "id": "ws-XdeUVMWShTesDMME", "type": "workspaces" } } }, "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": [ "run:applying", "run:completed", "run:created", "run:errored", "run:needs_attention", "run:planning" ], "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": "ws-XdeUVMWShTesDMME", "type": "workspaces" } } }, "links": { "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" } } ]}Show a Notification Configuration
GET /notification-configurations/:notification-configuration-id
| Parameter | Description |
|---|---|
:notification-configuration-id | The id of the notification configuration to show. |
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-AeUQ2zfKZzW9TiGZSample 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": [ "run:applying", "run:completed", "run:created", "run:errored", "run:needs_attention", "run:planning" ], "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": "ws-XdeUVMWShTesDMME", "type": "workspaces" } } }, "links": { "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" } }}Update a Notification Configuration
PATCH /notification-configurations/:notification-configuration-id
| Parameter | Description |
|---|---|
:notification-configuration-id | The id of the notification configuration to update. |
If theenabled attribute is true, updating the configuration will cause HCP Terraform to send a verification request. If a response is received, it will be stored and returned in thedelivery-responses attribute. More details in theNotification Verification and Delivery Responses section above.
| Status | Response | Reason |
|---|---|---|
| 200 | JSON API document (type: "notification-configurations") | Successfully updated the notification configuration |
| 400 | JSON API error object | Unable to complete verification request to destination URL |
| 404 | JSON API error object | Notification configuration not found, or user unauthorized to perform action |
| 422 | JSON API error object | Malformed request body (missing attributes, wrong types, etc.) |
Request Body
This PATCH endpoint requires a JSON object with the following properties as a request payload.
Ifenabled is set totrue, 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. SeeNotification Authenticity for more details. |
data.attributes.triggers | array | (previous value) | Array of triggers for sending notifications. SeeNotification 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" |
Sample Payload
{ "data": { "id": "nc-W6VGEi8A7Cfoaf4K", "type": "notification-configurations", "attributes": { "enabled": false, "name": "Slack: #devops", "url": "https://hooks.slack.com/services/T00000001/BC012345/0PWCpQmYyD4bTTRYZ53q4w", "destination-type": "slack", "token": null, "triggers": [ "run:created", "run:errored", "run:needs_attention" ], } }}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-W6VGEi8A7Cfoaf4KSample Response
{ "data": { "id": "nc-W6VGEi8A7Cfoaf4K", "type": "notification-configurations", "attributes": { "enabled": false, "name": "Slack: #devops", "url": "https://hooks.slack.com/services/T00000001/BC012345/0PWCpQmYyD4bTTRYZ53q4w", "destination-type": "slack", "token": null, "triggers": [ "run:created", "run:errored", "run:needs_attention" ], "delivery-responses": [], "created-at": "2019-01-08T21:34:28.367Z", "updated-at": "2019-01-08T21:49:02.103Z" }, "relationships": { "subscribable": { "data": { "id": "ws-XdeUVMWShTesDMME", "type": "workspaces" } } }, "links": { "self": "/api/v2/notification-configurations/nc-W6VGEi8A7Cfoaf4K" } },}Verify a Notification Configuration
POST /notification-configurations/:notification-configuration-id/actions/verify
| Parameter | Description |
|---|---|
:notification-configuration-id | The id of the notification configuration to verify. |
This will cause HCP Terraform to send a verification request for the specified configuration. If a response is received, it will be stored and returned in thedelivery-responses attribute. More details in theNotification Verification and Delivery Responses section above.
| 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/verifySample 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": [ "run:applying", "run:completed", "run:created", "run:errored", "run:needs_attention", "run:planning" ], "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": "ws-XdeUVMWShTesDMME", "type": "workspaces" } } }, "links": { "self": "/api/v2/notification-configurations/nc-AeUQ2zfKZzW9TiGZ" } }}Delete a Notification Configuration
This endpoint deletes a notification configuration.
DELETE /notification-configurations/:notification-configuration-id
| Parameter | Description |
|---|---|
:notification-configuration-id | The id of the notification configuration to delete. |
| 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