Implement Run Task integration callback API support

[TanyaSingh369-svg]

Description

Adds support for Terraform Run Task integration callbacks in the Python TFE SDK.

Changes included

• Added RunTaskIntegrations resource with callback support
• Added Run Task callback payload models
• Added validation for callback URL, access token, and callback status
• Added unit tests covering payload generation, validation, and callback requests
• Added example scripts for:
  - sending Run Task callbacks
  - receiving Terraform webhooks with FastAPI

This implementation allows users to send Run Task results back to Terraform using the callback URL and access token received in the webhook payload.

Testing plan

Unit tests

Ran:

pytest tests/units/test_run_task_integration.py -v

Verified:

• payload serialization
• callback request generation
• validation errors
• optional field handling
• callback headers
• JSON payload structure

End-to-end testing

Verified the integration flow locally using:

• Terraform Cloud / HCP Terraform
• FastAPI webhook server
• ngrok tunnel

Tested flow:

• Started local webhook server
• Exposed server using ngrok
• Configured Terraform Run Task with ngrok endpoint
• Triggered Terraform runs
• Received webhook payload successfully
• Extracted:
  - task_result_callback_url
  - access_token
• Sent callback response using SDK
• Verified successful Run Task status in Terraform

Example commands used:

uvicorn examples.run_task_webhook_server:app --reload --port 8000
ngrok http 8000
terraform apply

Output from tests

Unit tests completed successfully.

Example integration output:

=== EXTRACTED VALUES ===
callback_url: https://app.terraform.io/api/v2/...
access_token: v1.xxxxx...

Sending callback to: https://app.terraform.io/api/v2/...
Run task callback sent successfully

Terraform Run Task status:

Overall Result: Passed

Example Webhook output:

=== FULL PAYLOAD ===
{
"payload_version": 1,
"access_token": "Cddi7kxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"stage": "post_plan",
"is_speculative": false,
"task_result_id": "taskrs-FiaAxxxxxxxxxx",
"task_result_enforcement_level": "advisory",
"task_result_callback_url": "https://app.terraform.io/api/v2/xxxxxxxxxxxxxxxx",
"run_app_url": "https://app.terraform.io/app/prab-sandbox02/RunTask_test/runxxxxxxxxxxx",
"run_id": "run-Demxxxxxxxx",
"run_message": "Triggered via CLI",
"run_created_at": "2026-05-20T06:12:07.247Z",
"run_created_by": "tanya_singh369",
"workspace_id": "ws-Nn3Fsy8iw4voxxxx",
"workspace_name": "RunTask_test",
"workspace_app_url": "https://app.terraform.io/app/prab-sandbox02/RunTask_test",
"organization_name": "prab-sandbox02",
"vcs_repo_url": null,
"vcs_branch": null,
"vcs_pull_request_url": null,
"vcs_commit_url": null,
"configuration_version_id": "cv-Lpv2dF7xxxxxx",
"configuration_version_download_url": "https://app.terraform.io/api/v2/configuration-versions/cv-Lpv2dxxxxxx/download",
"workspace_working_directory": "",
"project_id": "prj-vhp5szCtbuxxxxxx",
"project_name": "Default Project",
"project_app_url": "https://app.terraform.io/app/prab-sandbox02/Default Project",
"plan_json_api_url": "https://app.terraform.io/api/v2/plans/plan-9DXkxxxxxxxxxx",
"capabilities": {
"outcomes": true
}
}

=== EXTRACTED VALUES ===
callback_url: https://app.terraform.io/api/v2/task-results/e8289ee8-7ab3-xxxxxxxxxxxxx/callback
access_token: Cddi7kOES2xqxA.atlasv1.pGwm9yc8xxxxxxxxxx
Sending callback to: https://app.terraform.io/api/v2/task-results/e8289ee8-7ab3-4f4f-972xxxxxxxxxx/callback
Run task callback sent successfully
INFO: 52.86.201.227:0 - "POST / HTTP/1.1" 200 OK