> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Terraform Webhook Setup Guide

> Configure Terraform to deliver events to StackOne.

## Prerequisites

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

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/guides/explore-connectors">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/terraform/guides/connector-profile/api-token" icon="https://stackone-logos.com/api/terraform/filled/png" horizontal>
        Terraform - API Token
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/guides/embedding-stackone-hub">StackOne Hub</a> or <a href="/guides/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/terraform/guides/link-account/api-token" icon="https://stackone-logos.com/api/terraform/filled/png" horizontal>
        Terraform - API Token
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Retrieve the Native Webhook URL</h2>

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

  <Steps>
    <Step title="Copy the Native Webhook URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Open this connection in StackOne and copy the <strong>Native Webhook URL</strong> field. It is unique to this connection and already contains the security token Terraform will call, so keep it secret.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Create the webhook notification in Terraform</h2>

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

  <Steps>
    <Step title="Open the workspace notification settings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In HCP Terraform, open the workspace, go to <strong>Settings > Notifications</strong>, and click <strong>Create a Notification</strong>.</p>

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/connectors/events-notifications.png" alt="Workspace Settings Notifications page with the Create a Notification button" />
      </div>
    </Step>

    <Step title="Configure the webhook destination">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fill in the notification as a webhook pointing at StackOne.</p>

        <ul>
          <li><strong>Destination</strong>: choose <strong>Webhook</strong>.</li>
          <li><strong>Notification Name</strong>: enter a name (for example, `StackOne`).</li>
          <li><strong>Webhook URL</strong>: paste the <strong>Native Webhook URL</strong> from this connection.</li>
          <li><strong>Token</strong> (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.</li>
        </ul>

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/connectors/events-webhook-config.png" alt="Create a Notification form showing the Webhook destination, Notification Name, Webhook URL, and Token fields" />
      </div>
    </Step>

    <Step title="Select the triggers and create the notification">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Under <strong>Run Events</strong>, choose <strong>All events</strong>, or choose <strong>Only certain events</strong> and pick the run triggers you want (Created, Planning, Needs attention, Applying, Completed, Errored). If the workspace has <strong>Health Assessments</strong> enabled, health-assessment triggers are also available. Click <strong>Create a notification</strong>. Terraform immediately sends a verification request to the URL, which StackOne answers automatically, so the notification becomes verified and enabled.</p>

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/stackone-60/connectors/events-triggers.png" alt="Run Events trigger selection with Only certain events chosen" />
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

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

  <Steps>
    <Step title="Review run events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired as a Terraform run moves through its stages.</p>

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

    <Step title="Review health assessment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired by workspace health assessments. These require <strong>Health Assessments</strong> to be enabled on the workspace.</p>

        <ul>
          <li><strong>Assessment Check Failure</strong> (`assessment:check_failure`) — Fired when one or more continuous validation checks fail.</li>
          <li><strong>Assessment Drift Detected</strong> (`assessment:drifted`) — Fired when configuration drift is detected for the first time.</li>
          <li><strong>Assessment Failed</strong> (`assessment:failed`) — Fired when a health assessment fails to run.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>How Terraform delivers events to StackOne.</p>

  <Steps>
    <Step title="Inspect the notification payload">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Handle verification requests">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>
  </Steps>
</section>

## 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.