> 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/vantage-api-reference/core-resources/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.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"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"}}}}}}}}}
```

## 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.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"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"}}}}}}}}}
```