> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/vantage-api/clients.md).

# Clients

## Get the registered webhook URL

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

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.09.16"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"schemas":{"ClientResponse":{"type":"object","properties":{"client_id":{"type":"string"},"customer_id":{"type":"string"},"webhook_url":{"type":"string"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/api/v1/clients/webhook-url":{"get":{"summary":"Get the registered webhook URL","tags":["clients"],"description":"The currently registered webhook destination for this environment (\"\" when none).","responses":{"200":{"description":"Current destination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Update webhook URL

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

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.09.16"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"schemas":{"UpdateWebhookUrlRequest":{"type":"object","properties":{"webhook_url":{"type":"string"}}},"ClientResponse":{"type":"object","properties":{"client_id":{"type":"string"},"customer_id":{"type":"string"},"webhook_url":{"type":"string"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]}}},"paths":{"/api/v1/clients/webhook-url":{"patch":{"summary":"Update webhook URL","tags":["clients"],"description":"Update or clear the webhook URL for the authenticated client. The\nwebhook URL must use HTTPS if provided, or can be empty to clear it.\nNote this means webhooks will no longer be sent to your previous\nendpoint.\n\nDeliveries to your endpoint carry an `X-Terra-Signature` header of the\nform `t=<timestamp>,v1=<hex-hmac>` where `t` is the send time in Unix\nseconds and `v1` is `HMAC-SHA256(secret, t + \".\" + payload)` — the\nsame scheme as all Terra webhooks. Verify by recomputing the HMAC\nfrom the received `t` and the raw body.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookUrlRequest"}}},"description":"Webhook URL update request","required":true},"responses":{"200":{"description":"Webhook URL updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientResponse"}}}},"400":{"description":"Bad request - invalid URL format or validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"description":"Client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```