RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://developer.hashicorp.com/terraform/cloud-docs/api-docs/notification-configurations below:

/notification-configurations API reference for HCP Terraform | Terraform

Notification configurations API reference

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 with Local execution mode do not support notifications.

Notifications are sent in response to triggers related to workspace events, and can be defined at workspace and team levels. You can specify workspace events in the triggers array attribute.

Workspace notification triggers

The following triggers are available for workspace notifications.

Display Name Value Description Created "run:created" A run is created and enters the Pending 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 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" 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_destroy_reminder" An automated workspace destroy run is imminent. Auto Destroy Results "workspace:auto_destroy_run_results" HCP Terraform attempted an automated workspace destroy run. Team notification triggers

The following triggers are available for team notifications.

Display Name Value Description Change Request "team:change_request" HCP Terraform sent a change request to a workspace that the specified team has explicit access to.

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 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"
    }
  ]
}

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.

You can trigger a test notification from the workspace notification settings page. You can read more about verifying a notification 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 like health assessments if you enable them for the workspace. Much of the information provides details about the associated assessment 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 of trigger_scope. There are two main values for trigger_scope: assessment and workspace, examples of which you can see below.

Health assessments

Health assessment notifications for workspace events contain the following information:

Note: Health assessments are available in HCP Terraform Plus and Premium editions. Refer to HCP Terraform pricing for details.

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

Note: Ephemeral workspaces, which automatically destroy infrastructure, are available in HCP Terraform Plus and Premium editions. Refer to HCP Terraform pricing for details.

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"
  }
}

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"]

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.

POST /workspaces/:workspace_id/notification-configurations

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, 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"
      ]
    }
  }
}

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-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": [
        "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"
    }
  }
}

Use the following endpoint to list all notification configurations for a workspace.

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. 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/workspaces/ws-XdeUVMWShTesDMME/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": [
          "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"
      }
    }
  ]
}

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-AeUQ2zfKZzW9TiGZ

Sample response

The type and id attributes in relationships.subscribable may also reference a "teams" and team ID, respectively.

{
  "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"
      }
  }
}

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

Parameter Description :notification-configuration-id The id of the notification configuration to update.

If the enabled 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 the delivery-responses attribute. More details in the Notification Verification and Delivery Responses section above.

Request body

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" 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-W6VGEi8A7Cfoaf4K

Sample 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"
    }
  },
}

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 the delivery-responses attribute. More details in the Notification 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/verify

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": [
          "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"
      }
  }
}

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

Team notifications allow you to configure relevant alerts that notify teams you specify whenever a certain event occurs.

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

Create a team notification configuration

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.

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. 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.

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"
      }
    }
  ]
}

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4