• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Terraform
  • Install
  • Tutorials
    • About the Docs
    • Configuration Language
    • Terraform CLI
    • Terraform Cloud
    • Terraform Enterprise
    • CDK for Terraform
    • Provider Use
    • Plugin Development
    • Registry Publishing
    • Integration Program
  • Registry(opens in new tab)
  • Try Cloud(opens in new tab)
  • Sign up
Terraform Home

Terraform Cloud

Skip to main content
  • Terraform Cloud
  • Plans and Features
  • Getting Started
    • Overview
    • Account
    • Agent Pools
    • Agent Tokens
    • Applies
    • Audit Trails
    • Assessment Results
    • Comments
    • Configuration Versions
    • Cost Estimates
    • Feature Sets
    • Invoices
    • IP Ranges
    • Notification Configurations
    • OAuth Clients
    • OAuth Tokens
    • Organizations
    • Organization Memberships
    • Organization Tags
    • Organization Tokens
    • Plan Exports
    • Plans
    • Policies
    • Policy Checks
    • Policy Sets
    • Policy Set Parameters
    • Projects
    • Project Team Access
    • Runs
      • Run Tasks
      • Stages and Results
      • Custom Integration
    • Run Triggers
    • SSH Keys
    • State Versions
    • State Version Outputs
    • Subscriptions
    • Team Membership
    • Team Tokens
    • Teams
    • User Tokens
    • Users
    • Variables
    • VCS Events
    • Workspaces
    • Workspace-Specific Variables
    • Workspace Team Access
    • Workspace Resources
    • Variable Sets
    • Changelog
    • Stability Policy
  • Migrating to Terraform Cloud

  • Terraform Cloud Agents

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  • Terraform Registry
    (opens in new tab)
  1. Developer
  2. Terraform
  3. Terraform Cloud
  4. API
  5. Run Tasks
  6. Custom Integration

»Run Tasks Integration API

Note: Run Tasks is a paid feature, available as part of the Team & Governance upgrade package. Refer to Terraform Cloud pricing for details.

Run tasks allow Terraform Cloud to interact with external systems at specific points in the Terraform Cloud run lifecycle. This page lists the API endpoints used to trigger a run task and the expected response from the integration.

Refer to run tasks for the API endpoints to create and manage run tasks within Terraform Cloud. You can also access a complete list of all run tasks in the Terraform Registry.

Run Task Request

When a run reaches the appropriate phase and a run task is triggered, Terraform Cloud will send a request to the run task's URL. The service receiving the run task request should respond with 200 OK, or Terraform Cloud will retry to trigger the run task.

POST :url

ParameterDescription
:urlThe URL configured in the run task to send requests to.
StatusResponseReason
200NothingSuccessfully submitted a run task

Request Body

The POST request submits a JSON object with the following properties as a request payload.

Common Properties

All request payloads contain the following properties.

Key pathTypeValuesDescription
payload_versioninteger1Schema version of the payload. Only 1 is supported.
access_tokenstringBearer token to use when calling back to Terraform Cloud.
stagestringpre_plan, post_plan, pre_applyThe run stage when Terraform Cloud triggers the run task.
is_speculativeboolWhether the task is part of a speculative run.
task_result_idstringID of task result within Terraform Cloud.
task_result_enforcement_levelstringmandatory, advisoryEnforcement level for this task.
task_result_callback_urlstringURL that should called back with the result of this task.
run_idstringId of the run this task is part of.
run_app_urlstringURL within Terraform Cloud to the run.
run_messagestringMessage that was associated with the run.
run_created_atstringWhen the run was started.
run_created_bystringWho created the run.
workspace_idstringId of the workspace the task is associated with.
workspace_namestringName of the workspace.
workspace_app_urlstringURL within Terraform Cloud to the workspace.
organization_namestringName of the organization the task is configured within.
vcs_repo_urlstringURL to the workspace's VCS repository. This is null if the workspace does not have a VCS repository.
vcs_branchstringRepository branch that the workspace executes from. This is null if the workspace does not have a VCS repository.
vcs_pull_request_urlstringURL to the Pull Request/Merge Request that triggered this run. This is null if the run was not triggered.
vcs_commit_urlstringURL to the commit that triggered this run. This is null if the workspace does not a VCS repository.

Pre-Plan Properties

Requests with stage set to pre_plan contain the following additional properties.

Key pathTypeValuesDescription
configuration_version_idstringThe ID of the configuration version for the run.
configuration_version_download_urlstringThe URL to download the configuration version. This is null if the configuration version is not available to download.
workspace_working_directorystringThe working directory specified in the run's workspace settings.

Post-Plan Properties

Requests with stage set to post_plan contain the following additional properties.

Key pathTypeValuesDescription
plan_json_api_urlstringThe URL to retrieve the JSON Terraform plan for this run.

Sample Payload

{
  "payload_version": 1,
  "access_token": "4QEuyyxug1f2rw.atlasv1.iDyxqhXGVZ0ykes53YdQyHyYtFOrdAWNBxcVUgWvzb64NFHjcquu8gJMEdUwoSLRu4Q",
  "stage": "post_plan",
  "is_speculative": false,
  "task_result_id": "taskrs-2nH5dncYoXaMVQmJ",
  "task_result_enforcement_level": "mandatory",
  "task_result_callback_url": "https://app.terraform.io/api/v2/task-results/5ea8d46c-2ceb-42cd-83f2-82e54697bddd/callback",
  "run_app_url": "https://app.terraform.io/app/hashicorp/my-workspace/runs/run-i3Df5to9ELvibKpQ",
  "run_id": "run-i3Df5to9ELvibKpQ",
  "run_message": "Triggered via UI",
  "run_created_at": "2021-09-02T14:47:13.036Z",
  "run_created_by": "username",
  "workspace_id": "ws-ck4G5bb1Yei5szRh",
  "workspace_name": "tfr_github_0",
  "workspace_app_url": "https://app.terraform.io/app/hashicorp/my-workspace",
  "organization_name": "hashicorp",
  "plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-6AFmRJW1PFJ7qbAh/json-output",
  "vcs_repo_url": "https://github.com/hashicorp/terraform-random",
  "vcs_branch": "main",
  "vcs_pull_request_url": null,
  "vcs_commit_url": "https://github.com/hashicorp/terraform-random/commit/7d8fb2a2d601edebdb7a59ad2088a96673637d22"
}

Request Headers

The POST request submits the following properties as the request headers.

NameValueDescription
Content-Typeapplication/jsonSpecifies the type of data in the request body
User-AgentTFC/1.0 (+https://app.terraform.io; TFC)Identifies the request is coming from Terraform Cloud
X-TFC-Task-SignaturestringIf the run task is configured with an HMAC Key, this header contains the signed SHA512 sum of the request payload using the configured HMAC key. Otherwise, this is an empty string.

Run Task Callback

Once a run task request has been fulfilled by the external integration, the integration must call back into Terraform Cloud with the result. Terraform expects this callback within 10 minutes, or the request will be considered to have errored.

PATCH :callback_url

ParameterDescription
:callback_urlThe task_result_callback_url specified in the run task request. Typically /task-results/:guid/callback.
StatusResponseReason
200NothingSuccessfully submitted a run task result
401JSON API error objectNot authorized to perform action
422JSON API error objectInvalid response payload. This could be caused by invalid attributes, or sending a status that is not accepted.

Request Body

The PATCH request submits a JSON object with the following properties as a request payload.

Key pathTypeDescription
data.typestringMust be "task-results".
data.attributes.statusstringThe current status of the task. Only passed, failed or running are allowed.
data.attributes.messagestring(Optional) A short message describing the status of the task.
data.attributes.urlstring(Optional) A URL where users can obtain more information about the task.

Status values other than passed, failed, or running return an error. Both the passed and failed statuses represent a final state for a run task. The running status allows one or more partial updates until the task has reached a final state.

{
  "data": {
    "type": "task-results",
    "attributes": {
      "status": "passed",
      "message": "4 passed, 0 skipped, 0 failed",
      "url": "https://external.service.dev/terraform-plan-checker/run-i3Df5to9ELvibKpQ"
    }
  }
}

Request Headers

The PATCH request must use the token supplied in the originating request (access_token) for authentication.

Edit this page on GitHub

On this page

  1. Run Tasks Integration API
  2. Run Task Request
  3. Run Task Callback
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)