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

# Terraform provider for X monitors & webhooks

> Install Xquik's Terraform provider and manage X monitors, signed webhooks, tweet actions, API keys, and durable automation state as infrastructure across teams.

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

Use the Terraform provider to manage Xquik resources with your infrastructure code. Platform teams can review account monitors, HMAC webhooks, API keys, drafts, tweet actions, profile updates, and support workflows through the same state process.

## Install

Install from the [Terraform Registry](https://registry.terraform.io/providers/Xquik-dev/x-twitter-scraper/latest). Declare the provider:

```hcl theme={null}
terraform {
  required_providers {
    x-twitter-scraper = {
      source  = "Xquik-dev/x-twitter-scraper"
      version = "~> 0.7.1"
    }
  }
}

provider "x-twitter-scraper" {
  api_key = var.xquik_api_key
}
```

Run `terraform init` before planning or applying resources.

## Authenticate

Use variables or environment variables for credentials:

```bash theme={null}
export X_TWITTER_SCRAPER_API_KEY="xq_YOUR_KEY_HERE"
export X_TWITTER_SCRAPER_BEARER_TOKEN="YOUR_OAUTH_TOKEN"
```

Prefer environment variables for credentials. If you pass credentials through Terraform variables, mark them `sensitive = true` and use an encrypted remote state backend.

## Workflow: monitor tweets to signed webhooks

Use this workflow when Terraform should own a production tweet monitor and the webhook endpoint that receives signed events for queues, incident tools, social listening dashboards, or CRM enrichment.

The provider resources map to the REST API: `x-twitter-scraper_monitor` creates an account monitor through `POST /monitors`. `x-twitter-scraper_webhook` creates a signed webhook through `POST /webhooks`. Both resources use Terraform snake\_case arguments that map to the API request fields.

```hcl theme={null}
variable "webhook_url" {
  type = string
}

variable "xquik_api_key" {
  type      = string
  sensitive = true
}

provider "x-twitter-scraper" {
  api_key = var.xquik_api_key
}

resource "x-twitter-scraper_webhook" "alerts" {
  url         = var.webhook_url
  event_types = ["tweet.new", "tweet.reply"]
  is_active   = true
}

resource "x-twitter-scraper_monitor" "xquik_account" {
  username    = "username"
  event_types = ["tweet.new", "tweet.reply"]
  is_active   = true
}

output "monitor_id" {
  value = x-twitter-scraper_monitor.xquik_account.id
}

output "webhook_id" {
  value = x-twitter-scraper_webhook.alerts.id
}

output "webhook_secret" {
  value     = x-twitter-scraper_webhook.alerts.secret
  sensitive = true
}
```

### Request mapping

<CardGroup cols={2}>
  <Card title="Monitor resource" icon="radio">
    Terraform resource `x-twitter-scraper_monitor` maps to `POST /monitors`. It requires `username` and `event_types`, accepts optional `is_active`, and returns `id`, `x_user_id`, `is_active`, and `created_at` in state.
  </Card>

  <Card title="Webhook resource" icon="webhook">
    Terraform resource `x-twitter-scraper_webhook` maps to `POST /webhooks`. It requires `url` and `event_types`, accepts optional `is_active`, and returns `id`, `secret`, and `created_at` in state.
  </Card>

  <Card title="Event data source" icon="activity">
    Terraform data source `x-twitter-scraper_event` reads one stored monitor event. It requires `id` and returns `type`, `username`, `monitor_id`, `occurred_at`, `x_event_id`, and `data`.
  </Card>
</CardGroup>

Tweet event types include `tweet.new`, `tweet.reply`, `tweet.quote`, and `tweet.retweet`. [Create Monitor](/api-reference/monitors/create) lists every type. Webhook URLs must use HTTPS and be reachable from the public internet.

### Returned data & handoff

After `terraform apply`, hand `monitor_id` to operators who need to pause, update, or delete the monitor through Terraform. Hand `webhook_id` to delivery dashboards and support playbooks. Store `webhook_secret` in a secret manager. Use it to verify `X-Xquik-Signature`, `X-Xquik-Timestamp`, and `X-Xquik-Nonce` on every delivery.

Production webhook payloads include `deliveryId` and `streamEventId`. Store `deliveryId` for receiver idempotency. Store `streamEventId` when you must process one monitor event once across retries or endpoint changes. Use `GET /webhooks/{id}/deliveries` to inspect retry state by webhook after apply. Synthetic `webhook.test` requests verify signing only. They omit those production idempotency fields.

Webhook operations are free. Active monitors check every second and cost 21
credits per monitor-hour. Creating one requires the username lookup cost and
the first monitor hour. Monitors may pause when credits run out.

### State & secrets

Terraform state can contain the webhook `secret` returned at creation time. Use an encrypted backend, restrict state access, and mark every output that references the secret as `sensitive = true`. If you lose or expose the secret, delete and recreate the webhook. Terraform then receives a new signing secret.

## Workflow: declare media tweets and replies

Use `x-twitter-scraper_x_tweet` when an infrastructure change must create one durable tweet or reply as part of a reviewed apply. The resource maps to `POST /x/tweets`, accepts public media URLs in `media`, and stores the confirmed `tweet_id` in Terraform state.

```hcl theme={null}
resource "x-twitter-scraper_x_tweet" "launch_reply" {
  account           = "myxhandle"
  text              = "Launch assets are ready"
  reply_to_tweet_id = "1893456789012345678"
  media             = ["https://example.com/product-demo.mp4"]
}

output "launch_reply_tweet_id" {
  value = x-twitter-scraper_x_tweet.launch_reply.tweet_id
}
```

### Tweet resource mapping

<CardGroup cols={2}>
  <Card title="Tweet resource" icon="send">
    Terraform resource `x-twitter-scraper_x_tweet` maps to `POST /x/tweets`. It requires `account`, accepts optional `text`, `reply_to_tweet_id`, `is_note_tweet`, `community_id`, and `media`, and returns `tweet_id` plus read-only tweet details in state.
  </Card>

  <Card title="Media boundary" icon="image">
    The `media` argument is for public image URLs or exactly 1 public MP4 URL. Text-only tweets and replies cost 30 credits. Attached media adds 2 credits per started MB. Do not pass uploaded media IDs to this resource. Uploaded media IDs are for direct messages through `POST /x/dm/{userId}`.
  </Card>
</CardGroup>

<Warning>
  Generated provider docs may list `media_ids` on `x-twitter-scraper_x_tweet`, but `POST /x/tweets` rejects `media_ids`. Use `media` with public image or MP4 URLs for tweets. Reserve uploaded media IDs for one-item DM `media_ids` through REST, MCP tools, or a generated SDK.
</Warning>

### Tweet handoff

After `terraform apply`, hand `tweet_id`, `reply_to_tweet_id`, `account`, and the original `media` URLs to the queue, release record, CRM note, or incident timeline that needs to reconcile the post. Keep the media URLs in your own system so a later state refresh does not become the only audit trail.

Terraform state for `x-twitter-scraper_x_tweet` does not expose durable write action fields, media upload resources, or direct-message send resources. Use the REST API, MCP tools, or a generated SDK when a worker must store lifecycle handoffs, upload local media for one-item DM `media_ids`, or store returned DM `message_id`.

## Error handling

Terraform prints provider errors during plan and apply. REST API response semantics match the [error handling guide](/guides/error-handling).

## State & pagination

Terraform tracks resource state in your configured backend. Data sources and resources use the generated provider schema. Review the generated docs in the [provider repository](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper/tree/main/docs) before adding resources to production state.

Do not hand off extraction files through Terraform. For reply, follower, or tweet search exports, use the REST extraction endpoints, CLI, MCP tools, or generated SDKs to write CSV, JSON, XLSX, or JSON Lines files. Keep Terraform state focused on long-lived resources and IDs that must be reviewed through plan and apply.

## Webhooks & references

* [REST API Overview](/api-reference/overview)
* [API Authentication](/api-reference/authentication)
* [Webhook Overview](/webhooks/overview)
* [Verify HMAC Signatures](/webhooks/verification)
* [Terraform Registry](https://registry.terraform.io/providers/Xquik-dev/x-twitter-scraper/latest) & [Source](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.