Run Tasks Integration API

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

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.

Post-Plan and Pre-Apply Properties

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

Sample Payload

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

Request Headers

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

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

Request Body

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

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.