Provision Orbit resources with Terraform

The Orbit Terraform provider lets platform teams provision and version Orbit CPaaS resources as code in CI — the same way they manage the rest of their cloud estate. It is a thin wrapper over the official Orbit Go SDK: the provider configures one SDK client, and each resource maps Terraform plan/state onto the Orbit REST API through it.

Early access. The provider’s source lives in the Orbit monorepo. As with the Go SDK, a github.com/devotel/terraform-provider-orbit release and a registry publish are still pending, so terraform init cannot pull the released binary yet. Build from source until the registry listing ships; the replace directive in the provider’s go.mod builds it against the in-repo SDK (run go mod tidy once to populate go.sum).

1. Configure the provider

The provider needs an API key — a dv_live_sk_… key minted in the dashboard under Settings → API Keys. Supply it either inline or through the environment; the argument is marked sensitive, so it never lands in the Terraform console output or state diagnostics.

Argument	Env var	Required	Description
`api_key`	`ORBIT_API_KEY`	yes	Orbit API key (`dv_live_sk_…`). Marked sensitive.
`base_url`	`ORBIT_BASE_URL`	no	Override the API base URL (defaults to production).

terraform {
  required_providers {
    orbit = {
      source = "registry.terraform.io/devotel/orbit"
    }
  }
}

provider "orbit" {
  # api_key may also be supplied via the ORBIT_API_KEY environment variable.
  api_key = var.orbit_api_key
}

In CI, keep the key out of config entirely — set ORBIT_API_KEY in the pipeline’s secret store and drop the api_key argument from the provider block.

2. Resources

Six resources cover the Terraform-manageable surface. Every one supports terraform import <addr> <id>.

Resource	API routes
`orbit_webhook_endpoint`	`POST/GET/PUT/DELETE /webhooks[/:id]`
`orbit_messaging_service`	`POST/GET/PATCH/DELETE /messaging/services[/:id]`
`orbit_number`	`POST /numbers/purchase`, `GET/PUT/DELETE /numbers/:id`
`orbit_subaccount`	`POST/GET/PUT/DELETE /subaccounts[/:id]`
`orbit_campaign`	`POST/GET/PUT/DELETE /campaigns[/:id]`
`orbit_agent`	`POST/GET/PUT/DELETE /agents[/:id]`

Every resource follows the same template: the provider configures one SDK client, and each resource maps Terraform plan/state onto the REST API through it.

`orbit_webhook_endpoint`

Attribute	Type	Notes
`id`	string (out)	Server-assigned identifier.
`url`	string	HTTPS delivery URL. Must not resolve to a private/loopback host.
`events`	list(string)	Event types to subscribe to. At least one.
`active`	bool	Defaults to `true`.
`description`	string	Optional, max 255 chars.
`timeout_seconds`	number	Optional per-endpoint delivery timeout (1..30s). Defaults to 30.
`secret`	string (in)	Optional signing secret (min 16 chars). Write-only; never read back.

`orbit_number`

Purchases a number from inventory (POST /numbers/purchase) and configures its inbound routing. phone_number and country_code force replacement; label, status, capabilities, forwarding_number, compliance_profile_id and tags are updated in place. Outbound termination is owned by the platform softswitch and is intentionally not configurable here.

`orbit_messaging_service`

Bundles a sender pool, opt-out list and delivery/throughput configuration for outbound SMS/MMS. mps_cap sets a messages-per-second throughput cap (omit for unbounded). Nullable attributes removed from config are cleared on the next apply.

`orbit_subaccount`

A child organization under the authenticated tenant with its own team-member ceiling, rate limit and opening credit balance. slug and initial_credits_cents force replacement. api_key is minted once at creation and exposed as a sensitive computed attribute — it is never read back.

`orbit_campaign`

A marketing campaign (blast / drip / journey). Campaigns are created in draft; sending is a runtime action and is not part of the declarative lifecycle.

`orbit_agent`

An AI agent — a named conversational assistant with a system prompt, model and generation settings. The resource manages the agent’s portable configuration; the tool registry, knowledge-base bindings and nested runtime config are managed through their own surfaces and are intentionally out of scope. type, status, model, temperature and max_tokens are server-defaulted when omitted.

3. Worked example: messaging service + webhook endpoint

This configuration purchases a number, wires a messaging service to it, and subscribes a webhook endpoint to delivery receipts:

terraform {
  required_providers {
    orbit = {
      source = "registry.terraform.io/devotel/orbit"
    }
  }
}

provider "orbit" {
  # ORBIT_API_KEY picked up from the environment.
}

resource "orbit_number" "support" {
  phone_number      = "+14155552671"
  country_code      = "US"
  label             = "Support line"
  forwarding_number = "+14155550000"
  tags              = ["support", "us"]
}

resource "orbit_messaging_service" "transactional" {
  label               = "Transactional"
  sender_pool_id      = orbit_number.support.id
  inbound_webhook_url = "https://hooks.example.com/inbound"
  sticky_sender       = true
  mps_cap             = 100
}

resource "orbit_webhook_endpoint" "delivery_status" {
  url             = "https://hooks.example.com/orbit"
  events          = ["message.delivered", "message.failed"]
  active          = true
  description     = "Production delivery receipts"
  timeout_seconds = 10
  secret          = var.orbit_webhook_secret
}

Plan and apply:

terraform init
terraform plan
terraform apply

apply prints the server-assigned ids. Bring pre-existing resources under management with terraform import:

terraform import orbit_webhook_endpoint.delivery_status whk_123
terraform import orbit_agent.support agt_123
terraform import orbit_number.support num_123

After each import, run terraform plan — it diffs the imported state against your config, and any attribute the config omits shows as drift to reconcile.

4. Drift and import patterns

Import-then-diff. terraform import pulls the resource’s current server state into the state file; it does not write config for you. After import, copy the attribute values from terraform state show <addr> into your .tf files so the next plan is empty.
Replacement-forcing attributes. Changing a force-replacement attribute (orbit_number.phone_number, orbit_subaccount.slug, orbit_subaccount.initial_credits_cents) destroys and recreates the resource on the next apply. Review the plan before approving.
Clearing nullable attributes. On orbit_messaging_service, removing a nullable attribute from config clears it server-side on the next apply — the dashboard and Terraform stay in sync both directions.
Write-only secrets. orbit_webhook_endpoint.secret and orbit_subaccount.api_key are never read back from the API, so Terraform cannot detect out-of-band changes to them. Rotate them by updating the variable and re-applying.
Detect out-of-band edits. terraform plan with no local changes reports any attribute drifted since the last apply; run it on a schedule (or terraform plan -refresh-only) to catch dashboard-side edits.

5. What is intentionally not configurable

Outbound voice and SMS termination is owned by the platform softswitch — no Terraform resource can set an outbound carrier, SIP trunk, or messaging route, and none ever will. The same holds for the agent tool registry and knowledge-base bindings (managed through their own surfaces) and for campaign sending, which is a runtime action, not declarative configuration. Everything else in the six resources above is supported.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Provision Orbit resources with Terraform

Provision Orbit resources with Terraform

1. Configure the provider

2. Resources

`orbit_webhook_endpoint`

`orbit_number`

`orbit_messaging_service`

`orbit_subaccount`

`orbit_campaign`

`orbit_agent`

3. Worked example: messaging service + webhook endpoint

4. Drift and import patterns

5. What is intentionally not configurable

See also

​Provision Orbit resources with Terraform

​1. Configure the provider

​2. Resources

​orbit_webhook_endpoint

​orbit_number

​orbit_messaging_service

​orbit_subaccount

​orbit_campaign

​orbit_agent

​3. Worked example: messaging service + webhook endpoint

​4. Drift and import patterns

​5. What is intentionally not configurable

​See also

Provision Orbit resources with Terraform

1. Configure the provider

2. Resources

`orbit_webhook_endpoint`

`orbit_number`

`orbit_messaging_service`

`orbit_subaccount`

`orbit_campaign`

`orbit_agent`

3. Worked example: messaging service + webhook endpoint

4. Drift and import patterns

5. What is intentionally not configurable

See also