Failed to Create Webhook on Repository When Changing Version Control Settings on a Workspace

Problem

When you attempt to change the version control (VCS) settings on a workspace in HCP Terraform or Terraform Enterprise, the UI displays a "Failed to create webhook repository" error.

Cause

This error typically occurs because the personal access token used for the VCS connection does not have administrative permissions for the target repository. Creating a webhook on a repository is an administrative action that requires admin level permissions.

Solutions

To diagnose and resolve this issue, you can perform the following steps using your VCS provider's API. These examples use the GitHub API.

Solution 1: Test Webhook Creation Directly with the API

You can attempt to create a test webhook directly against the repository using the same token configured in HCP Terraform or Terraform Enterprise. This isolates the issue from the Terraform platform and verifies if the token has sufficient permissions.

1. Execute the following curl command, replacing $token, test-user, and $repository-name with your values. This example uses the GitHub API to create a repository webhook.

   $ curl -H "Authorization: token $token" \
     -X POST \
     -H "Accept: application/vnd.github.v3+json" \
     "https://api.github.com/repos/test-user/$repository-name/hooks" \
     -d '{"name":"web","active":true,"events":["push","pull_request"],"config":{"url":"https://example.com/webhook","content_type":"json","insecure_ssl":"0"}}'

2. Review the result.
   • If the command succeeds, a webhook is created in your repository. You can verify this in your repository's webhook settings. This indicates the issue may not be related to permissions.
   • If the command fails, the API response should contain an error message similar to the one reported by HCP Terraform or Terraform Enterprise, confirming a permission issue.

Solution 2: Verify Repository Permissions with the API

You can check the specific permissions associated with your token for all accessible repositories.

1. Execute the following curl command, replacing $token with your value. This example uses the GitHub API to list repositories for the authenticated user.

   $ curl -H "Authorization: token $token" \
     https://api.github.com/user/repos | jq '.[] | "\(.permissions) \(.name)"'

2. Analyze the output to check the admin permission for the relevant repository.

   ## Example Output
   "{\"admin\":false,\"maintain\":true,\"push\":true,\"triage\":true,\"pull\":true} hashicups"
   "{\"admin\":false,\"maintain\":true,\"push\":true,\"triage\":true,\"pull\":true} localterraform"
   "{\"admin\":true,\"maintain\":true,\"push\":true,\"triage\":true,\"pull\":true} moduletest"
   "{\"admin\":true,\"maintain\":true,\"push\":true,\"triage\":true,\"pull\":true} null_resource"
   "{\"admin\":true,\"maintain\":true,\"push\":true,\"triage\":true,\"pull\":true} planexportest"

   In this example output, the token does not have admin permissions for the hashicups and localterraform repositories, which would prevent webhook creation.

3. To resolve the issue, navigate to your VCS provider's repository settings and grant admin permissions to the user or team associated with the token. After updating the permissions, attempt to create the webhook again through the HCP Terraform or Terraform Enterprise UI.