Introduction
Terraform Enterprise (TFE) uses webhook integration with VCS providers to monitor new commits and pull requests when using the UI/VCS-driven run workflow.
Occasionally, configuration issues or service interruptions will interfere with the expected operation of webhooks in TFE. This troubleshooting guide provides resources for determining when this is occurring and what the issue might be.
Background
In working with TFE’s VCS-driven run workflow, it’s helpful to understand that webhooks aren’t always used to trigger new runs. When a workspace is initially created, or when its settings are changed in TFE, the fetching of a new configuration version is not triggered by a webhook notification. Instead, TFE makes a request to the VCS for new configuration information.
Webhooks are triggered by pushes and PRs made to the repository. Currently, a webhook will be delivered to TFE for any of these events. A TFE workspace will respond to the webhook by pulling in the new Terraform configuration and creating a new run if the push was made to the VCS branch that the workspace tracks, or for any PR.
Troubleshooting steps
There are a few steps that are helpful in debugging webhook behavior for a particular workspace.
The related webhook is present
On most VCS providers, existing webhooks can be viewed in the repository settings, although the exact path varies by provider.
Once you’ve located the webhook settings, check that a webhook has been created on the repository with the base URL app.terraform.io or the URL of your private TFE instance. The webhook URL should match the one shown in the workspace’s “Version Control” settings area. These URLs use UUIDs, so check carefully for a match.
The webhook is configured to respond to the desired events
If the webhook is present, access its detailed settings to ensure that it is configured for push and pull request events. This is the default set of events, but if the webhook has been edited for any reason, it’s possible that the set of events it responds to was changed. If the webhook is configured to respond to pushes but not pull requests, Terraform runs will only be initiated on push to the target branch, not when a PR is opened.
The webhook is firing and receiving a success response
All supported VCS providers aside from Bitbucket Server provide a log of webhook deliveries. First, access the webhook detail, then check for the list of times the webhook fired. See if a webhook was sent for recent push events, and if so, whether it was successful (received a 200 OK from the TFE instance).
If the webhook wasn’t sent, double-check that the event should have triggered a delivery, and that the service provider is not (or was not, at the time) having issues. If it was sent but wasn’t successful, the error message will often be helpful in revealing the issue.
Some VCS providers retain this history only for a short period of time. If there are no recent events, initiate a push or pull request, or use the Test button, if one is available, to create a delivery.