Ellipse Gradient for Header

HCP Terraform Integration Guide

Integrate HCP Terraform with enterprise systems through its versioned REST API, selected webhook notifications, asynchronous run operations, and scheduled reconciliation workflows.

HCP Terraform integration options at a glance

HCP Terraform’s primary integration mechanism is a versioned REST API using JSON:API-style resources for organizations, projects, workspaces, runs, state versions, variable sets, teams, and policies. Selected Terraform events can generate webhook-style notifications for external HTTP endpoints, although coverage is not universal. Runs and configuration operations are asynchronous, so integrations should correlate identifiers and use notifications or controlled polling. Configuration versions and state versions may involve file upload or download operations. Martini can securely consume the API, receive supported webhook notifications, expose orchestration APIs, schedule reconciliation workflows, transform JSON:API responses, and apply authorization, validation, retry, and idempotency rules.

Integration pointSupported by HCP Terraform?Common use casesHow Martini supports it
REST APIsYesManage and query Organizations, Projects, Workspaces, Runs, State versions, Variable sets, Teams, Policies, and related Terraform resources using JSON:API-style requests.Martini can consume the versioned HCP Terraform REST API from workflows, map responses, follow pagination, and expose controlled APIs that orchestrate HCP Terraform operations.
Webhooks / outbound callbacksLimitedReceive notifications for selected Terraform events such as supported run or resource state changes.Martini can expose an HTTP endpoint or webhook-triggered workflow, validate the notification, retrieve authoritative resources, and route the result to downstream systems.
AuthenticationYesAuthenticate API requests with user, team, or organization bearer tokens; OAuth clients and tokens support documented external application integrations.Martini can store tokens and related credentials in secure environment configuration and attach authorization to API-consuming workflows.
Bulk / async / batch APIsLimitedCreate and monitor asynchronous Terraform runs and configuration operations; HCP Terraform does not use a general-purpose bulk API as its primary model.Martini can persist run identifiers, use notifications or controlled polling, apply backoff, and separate queued, running, successful, and failed outcomes.
File / attachment APIsLimitedUpload configuration versions and retrieve state-version artifacts where the relevant permissions and API operations allow it.Martini can transfer approved files or artifacts through workflows, while applying restricted credentials, secure storage, retention, and logging controls.
Scheduled synchronizationYesReconcile Organizations, Projects, Workspaces, Runs, State versions, policy metadata, or governance information on a recurring schedule.Martini can schedule workflows, process paginated collections, persist high-water marks, and publish changes to CMDB, reporting, or governance systems.
JSON:API resourcesYesHandle primary data, relationships, included resources, links, and metadata returned by HCP Terraform collection and resource endpoints.Martini can parse JSON, normalize nested relationships, map fields to canonical models, and preserve identifiers for subsequent API calls.

How HCP Terraform exposes data and business events

HCP Terraform REST APIs

HCP Terraform provides a versioned REST API with JSON:API-style resources for organizations, projects, workspaces, runs, state versions, variable sets, teams, policies, and related operations. Collection responses can be paginated and may represent relationships through links or included resources.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates with a least-privileged bearer token, calls the required HCP Terraform endpoint, follows pagination, normalizes JSON:API data and relationships, applies business rules, and writes the result to an enterprise target or returns it through a Martini API.

Implementation sequence

Authenticate with a team or organization API token stored as a Martini secret
Call the required HCP Terraform resource endpoint
Follow pagination links or parameters until the collection is complete
Normalize primary data, relationships, included resources, and metadata
Map fields to the target model and apply authorization rules
Write the result and record identifiers or a high-water mark

HCP Terraform Webhooks

HCP Terraform supports webhook-style notifications for selected events. Notifications can trigger external HTTP processing, but they are event-specific and should not be treated as a universal stream for every HCP Terraform object or lifecycle change.

Martini implementation pattern

Martini implementation pattern: expose a controlled HTTP endpoint or webhook-triggered workflow, validate the notification and expected event type, retrieve the authoritative Run, Workspace, or related resource through the REST API, then route the enriched result to downstream systems.

Implementation sequence

Receive the HCP Terraform notification
Validate the sender, payload, event type, and resource identifier
Retrieve the authoritative resource from the HCP Terraform REST API
Apply idempotency using an event or run identifier
Map the enriched event to the target system
Record the outcome and retry recoverable failures

Asynchronous Terraform Runs

Creating or queuing a Terraform run does not mean that planning or applying has completed. HCP Terraform exposes run status and related results, so integrations must treat initiation and completion as separate stages.

Martini implementation pattern

Martini implementation pattern: accept an approved request, resolve the workspace, call HCP Terraform to create or queue the run, persist the returned run identifier, and then use a supported notification or bounded polling with backoff to update the originating system.

Implementation sequence

Validate the approved operation and target workspace
Create or queue the HCP Terraform run
Persist the returned run identifier and correlation data
Wait for a supported notification or poll with bounded backoff
Retrieve final run and policy information
Update the requesting system and close or route the workflow

Configuration and State Versions

HCP Terraform provides configuration-version and state-version operations that can involve artifact upload or download rather than ordinary JSON resource updates. State contents may contain sensitive infrastructure information.

Martini implementation pattern

Martini implementation pattern: transfer only the approved artifact or metadata, use restricted credentials and secure storage, associate the artifact with its workspace and run identifiers, and keep state handling separate from general reporting logic.

Implementation sequence

Verify authorization and the required artifact operation
Upload or retrieve the configuration or state-version artifact
Associate the artifact with its workspace and run identifiers
Apply encryption, retention, and sensitive-data controls
Map approved metadata to the target repository or report
Record transfer status without logging secret contents

Common HCP Terraform integration patterns

Pattern 1: Synchronize Terraform runs to ServiceNow

When to use this pattern

Use this pattern when infrastructure changes must update an enterprise change record with plan, apply, policy, and failure outcomes. Selected HCP Terraform notifications can initiate processing, while the REST API supplies authoritative run and workspace details.

Integration direction
HCP Terraform
Martini
ServiceNow
Example Mapping
HCP Terraform FieldCanonical FieldTarget Field
Run.statusdeploymentStatusChange.state
Run.workspace.idworkspaceIdChange.configurationItem
Run.actionsexecutionActionChange.implementationSummary
Policy checksgovernanceOutcomeChange.riskOrComplianceStatus
Martini implementation pattern

Martini receives a supported notification, validates its event and run identifier, retrieves the Run and Workspace resources, enriches the payload with project and policy information, and updates ServiceNow. Stable run or event identifiers provide idempotency; transient API failures use bounded retries and terminal failures are routed for review.

Martini capabilities used
  • webhook-triggered workflows
  • API consumption
  • data mapping
  • business rules
  • error handling
  • retry and idempotency

Pattern 2: Start an approved Terraform run

When to use this pattern

Use this pattern when an approved ServiceNow, Jira, or release process should initiate an HCP Terraform run and receive its final outcome. Run creation and completion are handled as separate workflow stages.

Integration direction
ServiceNow
Martini
HCP Terraform
Example Mapping
HCP Terraform FieldCanonical FieldTarget Field
Change.numberrequestIdRun.message
Change.configurationItemworkspaceIdWorkspace.id
Change.approvedByapproverRun.attributes
Change.requestedActionexecutionActionRun.actions
Martini implementation pattern

Martini validates approval, resolves the authorized workspace, applies permitted metadata or variable-set logic, and calls HCP Terraform to create or queue the run. It stores the run ID, then processes a notification or polls with backoff before updating the source request. Unauthorized workspaces and policy failures are rejected or routed separately.

Martini capabilities used
  • REST API consumption
  • workflow orchestration
  • validation
  • conditional routing
  • data transformation
  • asynchronous processing

Pattern 3: Reconcile workspace inventory and governance

When to use this pattern

Use this pattern for scheduled inventory synchronization across organizations, projects, workspaces, teams, and policy metadata. It is useful for CMDB population, ownership reporting, and governance gap detection.

Integration direction
HCP Terraform
Martini
CMDB
Example Mapping
HCP Terraform FieldCanonical FieldTarget Field
Workspace.idresourceIdConfigurationItem.externalId
Workspace.nameresourceNameConfigurationItem.name
Project.idgroupIdConfigurationItem.serviceGroup
Workspace.execution-modeexecutionModeConfigurationItem.operatingModel
Martini implementation pattern

A scheduled Martini workflow lists authorized Organizations, Projects, and Workspaces across all pages, normalizes relationships, compares high-water marks or current identifiers with the CMDB, and creates, updates, or retires records according to business rules. Retryable failures are isolated by page or resource so one inaccessible workspace does not discard the full synchronization.

Martini capabilities used
  • scheduled workflows
  • pagination handling
  • incremental synchronization
  • mapping and transformation
  • business rules
  • error isolation

Pattern 4: Produce state and compliance reporting

When to use this pattern

Use this pattern when governance teams need run history, state-version metadata, workspace ownership, and policy outcomes in a reporting or compliance model without indiscriminately copying full Terraform state.

Integration direction
HCP Terraform
Martini
Datadog
Example Mapping
HCP Terraform FieldCanonical FieldTarget Field
State version.created-atstateSnapshotTimedeployment.stateSnapshotTime
Run.statusdeploymentStatusdeployment.status
Workspace.idworkspaceIddeployment.workspaceId
Policy checkspolicyOutcomedeployment.complianceStatus
Martini implementation pattern

Martini retrieves permitted state-version metadata and related Runs on a schedule, correlates them with Workspaces and policy results, transforms the data into a reporting model, and forwards approved operational metadata. Full state downloads are optional and require explicit authorization, secure handling, and retention controls.

Martini capabilities used
  • scheduled orchestration
  • REST API consumption
  • relationship enrichment
  • data mapping
  • security controls
  • monitoring

Applications commonly integrated with HCP Terraform

HCP Terraform commonly participates in source-control, delivery, service-management, collaboration, and observability workflows. Martini can coordinate these systems with HCP Terraform while keeping authentication, mapping, asynchronous run handling, and business rules in reusable workflows. The exact integration path depends on each application’s APIs and the organization’s HCP Terraform configuration.

Application Scenario Direction Martini Pattern
GitHub Associate HCP Terraform workspaces and runs with repositories, commits, pull requests, and configuration changes. GitHub → Martini → HCP Terraform Martini can receive repository or delivery events, resolve the target workspace, validate the requested operation, and call the HCP Terraform REST API. It can correlate the returned run identifier with the source change and route status updates back to the relevant process.
GitLab Link infrastructure changes to repositories, merge requests, and CI/CD workflows. GitLab → Martini → HCP Terraform A Martini workflow can consume GitLab API data or notifications, map project and environment metadata to HCP Terraform workspaces, start or inspect runs, and return run or policy outcomes to the delivery workflow.
Bitbucket Connect Terraform configuration to source repositories and delivery workflows. Bitbucket → Martini → HCP Terraform Martini can orchestrate API calls between Bitbucket and HCP Terraform, validate repository-to-workspace relationships, and persist run identifiers for asynchronous status tracking.
Azure DevOps Coordinate Terraform runs with Azure Repos, pipelines, release approvals, and deployment metadata. Azure DevOps → Martini → HCP Terraform Martini can receive an approved pipeline or release request, resolve the HCP Terraform workspace, apply permitted metadata or variables, initiate a run, and update Azure DevOps when the run reaches a terminal status.
ServiceNow Create or update change records using Terraform plans, applies, failures, and policy outcomes. ServiceNow → Martini → HCP Terraform Martini can retrieve an approved change, validate its workspace and requested action, call HCP Terraform to create a run, and synchronize run, policy, and completion status back to ServiceNow with duplicate protection.
Jira Link infrastructure changes and Terraform runs to issues, approvals, and delivery records. Jira → Martini → HCP Terraform A workflow can use Jira issue data as the business authorization, call HCP Terraform for workspace and run operations, and add a structured status update when the asynchronous run completes or fails.
Slack Notify engineering and operations teams about run completion, failures, policy violations, or approval requirements. HCP Terraform → Martini → Slack Martini can receive a supported HCP Terraform notification, retrieve authoritative Run and Workspace resources, format a policy-aware message, and route it to the appropriate Slack destination through the configured Slack integration.
Datadog Correlate infrastructure deployment activity with operational monitoring and service ownership data. HCP Terraform → Martini → Datadog A scheduled or event-driven workflow can collect run and workspace metadata, normalize it into deployment or change events, and forward approved observability data to Datadog while excluding sensitive state contents.

How to build a HCP Terraform integration in Martini

Objective

Establish access to HCP Terraform with credentials appropriate for unattended enterprise integration and the required organization, project, workspace, run, or state permissions.

Instructions in Martini

  • Use a team or organization API token where appropriate for service automation
  • Store bearer tokens and webhook-related secrets in Martini environment secrets
  • Configure the HCP Terraform API base URL and explicitly target the documented API version
  • Grant the least privilege required for the workflow

Objective

Select an event-driven, API-led, or scheduled entry point based on the integration’s freshness and reliability requirements.

Instructions in Martini

  • Use a webhook-triggered workflow for supported HCP Terraform events
  • Use a scheduled workflow for reconciliation, reporting, or controlled polling
  • Expose a Martini REST API for approved external requests to orchestrate HCP Terraform operations
  • Do not assume every HCP Terraform object or lifecycle event produces a webhook

Objective

Receive notifications or call HCP Terraform to obtain authoritative resource data, including related objects required by downstream business rules.

Instructions in Martini

  • Validate notification payloads before processing
  • Retrieve the Run, Workspace, Project, or State version through the REST API
  • Follow collection pagination links or parameters
  • Persist resource identifiers, timestamps, and correlation values

Objective

Coordinate HCP Terraform operations with enterprise approvals, deployment processes, governance checks, and downstream updates.

Instructions in Martini

  • Resolve the organization, project, and workspace context
  • Create or queue runs only after required approval and authorization checks
  • Persist asynchronous run identifiers
  • Use notification processing or bounded polling for completion

Objective

Convert JSON:API resources, relationships, links, and metadata into canonical deployment, change, inventory, or compliance models.

Instructions in Martini

  • Map primary data and related resources explicitly
  • Normalize status, action, timestamp, ownership, and policy fields
  • Avoid assuming every relationship is embedded in a response
  • Exclude sensitive state contents unless the use case requires them

Objective

Enforce workspace authorization, allowed actions, policy outcomes, duplicate protection, and sensitive-data handling before writing to target systems.

Instructions in Martini

  • Validate permitted organizations, projects, and workspaces
  • Route policy failures and unauthorized requests separately
  • Use stable event or run identifiers for idempotency
  • Apply retention and access rules to state-related data

Common HCP Terraform data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
OrganizationsTop-level administrative boundaries containing projects, workspaces, teams, policies, variables, and runs.CMDBs, governance platforms, identity administration, data warehousesMartini retrieves authorized organizations, maps ownership and governance attributes, and uses organization identifiers to scope downstream workflows.
ProjectsGroups of workspaces used for organization and access management.CMDBs, governance applications, reporting platformsMartini synchronizes project metadata, resolves project-to-workspace relationships, and applies filtering or ownership rules.
WorkspacesCore execution resources containing configuration, variables, state, run history, and execution settings.ServiceNow, Jira, CMDBs, release platformsMartini uses workspace identifiers to validate requests, initiate runs, correlate notifications, and map environment and ownership data.
RunsTerraform plan and apply executions with status, actions, configuration, workspace, policy, and timestamp information.ServiceNow, Jira, Slack, release platforms, observability systemsMartini creates or retrieves Runs, persists run IDs, polls or processes notifications, applies terminal-state rules, and prevents duplicate updates.
State versionsTerraform state snapshots associated with workspaces and runs.Approved artifact storage, compliance platforms, reporting systemsMartini should retrieve state metadata by default and download full state only when required, authorized, securely stored, and subject to retention controls.
Variable setsReusable collections of Terraform variables applied across workspaces or projects.Governance platforms, deployment services, workspace administration toolsMartini can query and coordinate variable-set assignments while validating workspace scope and avoiding exposure of sensitive variable values.

Authentication and security considerations

Bearer-token authentication

HCP Terraform API requests use bearer tokens. User, team, and organization API tokens are available, while OAuth clients and tokens support documented external application integrations.

Least-privilege access

Authentication does not guarantee authorization. Effective access depends on the token type, organization membership, team permissions, workspace permissions, and HCP Terraform access controls.

Secret and state protection

  • Store API tokens and webhook credentials in Martini environment secrets.
  • Prefer team or organization credentials for unattended integrations rather than personal user tokens.
  • Do not place tokens in workflow definitions, mappings, source control, logs, or error messages.
  • Treat Terraform state as sensitive infrastructure data and use restricted access, encryption, and retention controls.

Operational considerations for HCP Terraform integrations

Rate limits and pagination

Avoid uncontrolled polling, use bounded concurrency and exponential backoff, handle HTTP 429 responses centrally, and process every page returned by collection endpoints.

Asynchronous runs

Persist the HCP Terraform run identifier and treat run creation and completion as separate stages. Use supported notifications or controlled polling until a terminal status is reached.

Idempotency and webhooks

Webhook delivery and retries can produce duplicate processing. Use stable event, run, or resource identifiers before creating downstream changes, notifications, or compliance records.

API and schema evolution

Target the documented API version, validate required fields, tolerate unknown fields where safe, monitor deprecation notices, and keep resource mappings separate from business logic.

Testing and monitoring

Test authorized and unauthorized workspaces, pagination, policy failures, duplicate notifications, rate-limit responses, and incomplete relationships. Monitor workflow logs and preserve correlation identifiers for troubleshooting.

Why use Martini instead of scripts or point-to-point integrations?

Orchestration beyond point-to-point calls

Scripts can call the HCP Terraform API, but Martini provides a maintainable workflow layer for approvals, webhook handling, asynchronous run monitoring, scheduled reconciliation, and downstream updates.

Reusable integration logic

Martini centralizes authentication, validation, mappings, business rules, retries, and error routing so the same HCP Terraform behavior can support service management, delivery, governance, and reporting processes.

Controlled APIs and data models

Martini can expose a controlled API façade and transform JSON:API resources into canonical enterprise models without distributing HCP Terraform credentials or resource-specific logic across every consuming application.

Operational reliability

Workflows can handle pagination, high-water marks, idempotency, bounded polling, sensitive state controls, and observable failure paths more consistently than isolated scripts.

Frequently asked questions

How can HCP Terraform be integrated with enterprise systems?

HCP Terraform can be integrated through its versioned REST API, selected webhook notifications, asynchronous run operations, and scheduled reconciliation workflows. The API exposes organizations, projects, workspaces, runs, state versions, variable sets, teams, and policy-related resources using JSON:API-style responses.

Can Martini integrate with HCP Terraform?

Yes. Martini can consume the HCP Terraform REST API, receive supported webhook notifications, expose APIs for controlled orchestration, and run scheduled synchronization workflows. No dedicated native Martini connector is confirmed in the supplied documentation.

Do I need a connector to integrate HCP Terraform with Martini?

No. A dedicated HCP Terraform connector is not required. Martini can use HCP Terraform’s documented REST API, supported webhook notifications, bearer-token authentication, and related HTTP operations.

Is there any extra Lonti cost to integrate HCP Terraform with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate HCP Terraform. The integration is subject to the provisioned capacity of the Martini environment. HCP Terraform, cloud infrastructure, and other third-party services may impose separate subscription or usage charges.

Which HCP Terraform integration method should an enterprise use?

The REST API is the primary integration method for querying and managing HCP Terraform resources. Webhooks are useful for selected event notifications, while scheduled workflows are appropriate for reconciliation and reporting. GraphQL and SOAP APIs were not confirmed for HCP Terraform.

Can Martini receive HCP Terraform events and monitor runs?

Martini can receive supported HCP Terraform webhook notifications through an HTTP endpoint or webhook-triggered workflow. Because coverage is event-specific, integrations should verify the required event and retrieve the authoritative Run or Workspace resource. Alternatively, Martini can poll run status with bounded retries and backoff.

How does synchronization and data mapping work?

Martini can synchronize authorized Organizations, Projects, Workspaces, Runs, State versions, and related objects by processing paginated REST responses, persisted identifiers, timestamps, or high-water marks. Mappings can normalize JSON:API primary data, relationships, included resources, links, and metadata into deployment, inventory, governance, or compliance models.

How are HCP Terraform errors, retries, and duplicates handled?

Martini workflows can validate responses, isolate page or resource failures, retry transient failures with bounded backoff, and route terminal errors for review. Stable event, run, and resource identifiers can provide idempotency for webhook retries and prevent duplicate ServiceNow changes, Jira updates, notifications, or reporting records.

Can Martini expose an API façade for HCP Terraform?

Yes. Martini can expose a controlled REST API that accepts approved enterprise requests, validates organization and workspace access, orchestrates HCP Terraform REST API calls, tracks asynchronous run identifiers, and returns or publishes normalized status without exposing HCP Terraform credentials to every consuming application.

Related Martini documentation

Martini APIs

Workflows

Data and security

Reliability

Integrate HCP Terraform with Martini

Use Martini to connect HCP Terraform’s REST API and selected webhook notifications with enterprise workflows, service management, governance, reporting, and delivery systems.

EXPLORE MARTINI
BOOK A DEMO