How-to check a VCS webhook registry module connection on Terraform Enterprise FDO

Introduction

When we publish a private registry module on Terraform Enterprise, we use a VCS provider connection  to integrate our Version Control System (VCS). 

Once that is done, a webhook is created on the VCS side to communicate between Terraform Enterprise (TFE) and the VCS. 

The webhook will communicate with Terraform Enterprise when a new release of the code is done.

Expected Outcome

With the steps on this document we should be able to verify if a Webhook message is being received or not.

Prerequisites (if applicable)

• Have a Terraform Enterprise admin token
• Have the ability to login to the Terraform Enterprise server using ssh
• Installed a tool called jq for visibility of the API json output. Download here

Use Case

Use this document when you are trying to check if Terraform Enterprise is able to properly communicate with the VCS via webhooks.

This document is specifically created for Terraform Enterprise Flexible Deployment Option (FDO), the steps for the Replicated versions may differ.

Procedure

We will check if the communication between Terraform Enterprise and the VCS through the webhook when a new TAG publish is not being shown. 

• First, get the Webhook URL for the Terraform Enterprise private registry module by running the following commands: 

  export TOKEN=<your token>
  export hostname=<your_TFE_FQDN>
  export organization=<your organization name>
  export workspace=<your workspace name>
  export module=<your module name>
  export provider=<your provider name>

• With the above in hand, run the following command to grab the webhook URL expected by Terraform Enterprise. 

  curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://${hostname}/api/v2/organizations/${organization}/registry-modules/private/${organization}/${module}/${provider} |jq '.data.attributes."vcs-repo"."webhook-url"'

• The output should be something similar to this: 

  "https://<your_TFE_FQDN>/webhooks/vcs/88fb4db7-86e5-4026-9b4c-885b10ec32ec"

• The above output should be the same that is shown on the VCS repository settings. For example, this is the output of the above in GitHub (Github -> Repository -> Settings -> Webhooks)
  
  
  

Publish a new version and check the logs

With the info above, we now can grab the logs. To do that we should proceed as follows:

• Publish a new TAG release in GitHub. (Check this document for more info).
• On your Terraform Enterprise server, check the NGINX access logs for the webhook communication:

  docker exec terraform-enterprise-tfe-1 grep 88fb4db7-86e5-4026-9b4c-885b10ec32ec /var/log/terraform-enterprise/nginx-access.log

• The output of the above command should be something similar to this: 

  140.82.115.250 - - [24/Mar/2025:11:27:26 +0000] "POST /webhooks/vcs/88fb4db7-86e5-4026-9b4c-885b10ec32ec HTTP/1.1" 200 2 "-" "GitHub-Hookshot/6ca16fb"
  80.61.165.35 - - [26/Mar/2025:10:17:53 +0000] "GET /webhooks/vcs/88fb4db7-86e5-4026-9b4c-885b10ec32ec HTTP/1.1" 500 55 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36"
  140.82.115.192 - - [26/Mar/2025:10:20:32 +0000] "POST /webhooks/vcs/88fb4db7-86e5-4026-9b4c-885b10ec32ec HTTP/1.1" 200 2 "-" "GitHub-Hookshot/2fbdb2c"
  140.82.115.208 - - [26/Mar/2025:10:20:49 +0000] "POST /webhooks/vcs/88fb4db7-86e5-4026-9b4c-885b10ec32ec HTTP/1.1" 200 2 "-" "GitHub-Hookshot/2fbdb2c"
  140.82.115.192 - - [26/Mar/2025:10:21:27 +0000] "POST /webhooks/vcs/88fb4db7-86e5-4026-9b4c-885b10ec32ec HTTP/1.1" 200 2 "-" "GitHub-Hookshot/2fbdb2c"

Result

If there's no output on the command above, it means no communication between Terraform Enterprise and the VCS webhook is in place. 

In that case, please verify the following:

• Is there something blocking it on the network like a firewall/WAF/Proxy
• Is the certificate used on Terraform Enterprise for TLS trusted by the VCS environment. The following should be executed on your VCS environment and return an OK result.

  curl https://<your_TFE_fqdn>/_health_check

If you do get a result in the NGINX access logs then please create a ticket with HashiCorp support where we can help you further. 

• Share the results from this KB article as an attachment to the ticket
• Please share a Terraform Support Bundle as described here

Additional Information

• For information on the same checks for Terraform Enterprise workspaces, check this other KB.

• Some more info about webhooks troubleshooting on Terraform enterprise can be found here.