Clients

Get the registered webhook URL

get

The currently registered webhook destination for this environment ("" when none).

Authorizations

AuthorizationstringRequired

Authenticate with your Terra API credentials: username = your Terra dev-id, password = your Terra API key — the same credentials used for every other Terra API. The header pair dev-id + x-api-key is also accepted. Suspended credentials receive 403; accounts without the Vantage entitlement receive 403 once entitlement enforcement is enabled.

Responses

200

Current destination

application/json

client_idstringOptionalExample: client_abc123

customer_idstringOptionalExample: cust_xyz789

webhook_urlstringOptionalExample: https://your-domain.com/webhooks/terra

500

Internal server error

application/json

get/api/v1/clients/webhook-url

GET /api/v1/clients/webhook-url HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*

{
  "client_id": "client_abc123",
  "customer_id": "cust_xyz789",
  "webhook_url": "https://your-domain.com/webhooks/terra"
}

Update webhook URL

patch

Update or clear the webhook URL for the authenticated client. The webhook URL must use HTTPS if provided, or can be empty to clear it. Note this means webhooks will no longer be sent to your previous endpoint.

Deliveries to your endpoint carry an X-Terra-Signature header of the form t=<timestamp>,v1=<hex-hmac> where t is the send time in Unix seconds and v1 is HMAC-SHA256(secret, t + "." + payload) — the same scheme as all Terra webhooks. Verify by recomputing the HMAC from the received t and the raw body.

Authorizations

AuthorizationstringRequired

Authenticate with your Terra API credentials: username = your Terra dev-id, password = your Terra API key — the same credentials used for every other Terra API. The header pair dev-id + x-api-key is also accepted. Suspended credentials receive 403; accounts without the Vantage entitlement receive 403 once entitlement enforcement is enabled.

Body

webhook_urlstringOptionalExample: https://your-domain.com/webhooks/terra

Responses

200

Webhook URL updated successfully

application/json

client_idstringOptionalExample: client_abc123

customer_idstringOptionalExample: cust_xyz789

webhook_urlstringOptionalExample: https://your-domain.com/webhooks/terra

400

Bad request - invalid URL format or validation error

application/json

401

Unauthorized - invalid client credentials

application/json

404

Client not found

application/json

500

Internal server error

application/json

patch/api/v1/clients/webhook-url

PATCH /api/v1/clients/webhook-url HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "webhook_url": "https://your-domain.com/webhooks/terra"
}

{
  "client_id": "client_abc123",
  "customer_id": "cust_xyz789",
  "webhook_url": "https://your-domain.com/webhooks/terra"
}