How to verify a VCS webhook is being received by Terraform Enterprise

Introduction

Terraform Enterprise can connect a workspace with a Version Control System (VCS) provider, as described in the VCS provider documentation. This integration uses webhooks to alert Terraform Enterprise to new commits or pull requests, which triggers a run in the connected workspace.

Problem

When a VCS event (such as a new commit) occurs but does not trigger a run in Terraform Enterprise, there may be a communication issue preventing the webhook from being received.

This guide provides steps to verify that Terraform Enterprise is successfully receiving webhook messages from your VCS provider.

Expected Outcome

You will be able to confirm whether a webhook message from your VCS provider is successfully received by your Terraform Enterprise instance.

Prerequisites

• A Terraform Enterprise administrative user token.
• SSH access to the Terraform Enterprise server.
• The jq command-line tool installed on your local machine. You can find download instructions on the official jq website.

Procedure

Follow these steps for a single workspace that is not executing runs after a change in the linked VCS repository.

1. Retrieve the Webhook URL from Terraform Enterprise

   Use the Terraform Enterprise API to get the unique webhook URL for your workspace. Set the environment variables and run the following command.

   $ export TOKEN="<your_token>"
   $ export TFE_HOSTNAME="<your_tfe_fqdn>"
   $ export ORGANIZATION="<your_organization_name>"
   $ export WORKSPACE="<workspace_name>"
   
   $ curl \
     --header "Authorization: Bearer $TOKEN" \
     --header "Content-Type: application/vnd.api+json" \
     https://"${TFE_HOSTNAME}"/api/v2/organizations/"${ORGANIZATION}"/workspaces/"${WORKSPACE}" | jq '.data.attributes."vcs-repo"."webhook-url"'

   The command returns the webhook URL.

   "https://<your_TFE_fqdn>/webhooks/vcs/ed734c1b-0c4f-453b-902f-ecf0b41cf715"

2. Verify the Webhook URL in Your VCS Provider

   Confirm that the URL from the previous step matches the payload URL configured in your VCS provider's repository settings. The following example shows the webhook configuration page in GitHub.

   

3. Trigger a New Webhook

   Create a new commit or pull request in the repository to trigger a new webhook event to be sent to Terraform Enterprise.

4. Check Terraform Enterprise Logs for the Webhook

   Check the nginx logs on your Terraform Enterprise instance to see if the incoming webhook request was received. Use the unique ID from the webhook URL to search the logs.

   For Replicated Deployments

   ## Replace the example ID with the unique ID of your webhook
   $ docker logs tfe-nginx 2>&1 | grep ed734c1b-0c4f-453b-902f-ecf0b41cf715

   For Flexible Deployment Options (FDO)

   $ docker exec terraform-enterprise-tfe-1 grep ed734c1b-0c4f-453b-902f-ecf0b41cf715 /var/log/terraform-enterprise/nginx.log

   A successful entry in the log will resemble the following output, showing an HTTP 200 status code.

   140.82.115.148 - - [06/Sep/2023:12:33:58 +0000] "POST /webhooks/vcs/ed734c1b-0c4f-453b-902f-ecf0b41cf715 HTTP/1.1" 200 12 "-" "GitHub-Hookshot/435afa9"

Troubleshooting

If the webhook entry does not appear in the nginx logs, investigate the following potential issues:

• Network Connectivity: Ensure that no firewall, Web Application Firewall (WAF), or proxy is blocking traffic between your VCS provider and the Terraform Enterprise instance.

• TLS Certificate Trust: Verify that the TLS certificate used by Terraform Enterprise is trusted by your VCS provider's environment. You can run the following command from your VCS environment to check the health endpoint. A successful connection should return an OK status.

  $ curl https://<your_TFE_fqdn>/_health_check

If a successful entry appears in the logs but runs are still not triggering, the issue may be within the Terraform Enterprise application itself. Review the application logs for errors related to run creation or VCS processing.

Additional Information

• For more troubleshooting steps, refer to the article on Troubleshooting VCS webhooks in Terraform Enterprise.