Skip to main content

​
Prerequisites

Before continuing, you should have already completed the following for this connector:
1

Configure the Connector

Enable the connector and set up its connector profile in your project. See Managing Connectors.
https://stackone-logos.com/api/terraform/filled/png

Connector Profile

Terraform - API Token
2

Link an Account

Connect an account using StackOne Hub or Auth Link.
https://stackone-logos.com/api/terraform/filled/png

Link Account

Terraform - API Token

​
Retrieve the Native Webhook URL

StackOne generates a unique Native Webhook URL for this connection, which you paste into Terraform when creating the notification.

1

Copy the Native Webhook URL

Open this connection in StackOne and copy the Native Webhook URL field. It is unique to this connection and already contains the security token Terraform will call, so keep it secret.

​
Create the webhook notification in Terraform

Register the Native Webhook URL as a webhook Notification Configuration on each workspace you want events from.

1

Open the workspace notification settings

In HCP Terraform, open the workspace, go to Settings > Notifications, and click Create a Notification.

Workspace Settings Notifications page with the Create a Notification button
2

Configure the webhook destination

Fill in the notification as a webhook pointing at StackOne.

  • Destination: choose Webhook.
  • Notification Name: enter a name (for example, StackOne).
  • Webhook URL: paste the Native Webhook URL from this connection.
  • Token (optional): a secret Terraform uses to sign each request with an HMAC. StackOne relies on the unguessable URL token instead, so you can leave this blank.
Create a Notification form showing the Webhook destination, Notification Name, Webhook URL, and Token fields
3

Select the triggers and create the notification

Under Run Events, choose All events, or choose Only certain events and pick the run triggers you want (Created, Planning, Needs attention, Applying, Completed, Errored). If the workspace has Health Assessments enabled, health-assessment triggers are also available. Click Create a notification. Terraform immediately sends a verification request to the URL, which StackOne answers automatically, so the notification becomes verified and enabled.

Run Events trigger selection with Only certain events chosen

​
Available webhook events

The events below can be delivered to StackOne. Only the triggers you enable on the notification are sent.

1

Review run events

Fired as a Terraform run moves through its stages.

  • Run Created (run:created) — Fired when a run begins and enters the pending stage.
  • Run Planning (run:planning) — Fired when a run acquires the lock and starts to execute.
  • Run Needs Attention (run:needs_attention) — Fired when a plan has changes and requires user input.
  • Run Applying (run:applying) — Fired when a run enters the apply stage.
  • Run Completed (run:completed) — Fired when a run completes successfully.
  • Run Errored (run:errored) — Fired when a run terminates early due to an error or cancellation.
2

Review health assessment events

Fired by workspace health assessments. These require Health Assessments to be enabled on the workspace.

  • Assessment Check Failure (assessment:check_failure) — Fired when one or more continuous validation checks fail.
  • Assessment Drift Detected (assessment:drifted) — Fired when configuration drift is detected for the first time.
  • Assessment Failed (assessment:failed) — Fired when a health assessment fails to run.

​
Delivery format

How Terraform delivers events to StackOne.

1

Inspect the notification payload

Terraform sends each event as an HTTP POST with a JSON body containing a notifications array. StackOne routes on the trigger of the first entry (for example run:completed), and the payload also carries the run and workspace details.

2

Handle verification requests

When the notification is enabled or re-verified, Terraform sends a verification trigger. StackOne responds automatically so the notification becomes verified — no action is needed from you.

​
Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.