> 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/admin-api/webhook-signing-secrets.md).

# Webhook signing secrets

Read and rotate the secrets that Unified API and Vantage webhook deliveries are signed with.

A signing secret is the key Terra signs each webhook delivery with, so your receiver can check the delivery came from Terra. Each webhook you create gets its own. To verify a delivery, see [Webhooks](https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/webhooks#signing-secret).

| Webhook                         | Read the secret                                                         | Rotate the secret                                                                                                |
| ------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Unified API webhook destination | `GET …/unified-api/destinations/{destination_id}/secrets` (`keys:read`) | `POST …/unified-api/destinations/{destination_id}/signing-secret/rotate` (`destinations:write` and `keys:write`) |
| Vantage webhook                 | `GET …/vantage/webhook/secrets` (`keys:read`)                           | Not available in the Admin API                                                                                   |

In this table, `…` stands for `/environments/{dev_id}`.

## Get the secret when you create a webhook

```http
POST /environments/{dev_id}/unified-api/destinations
```

```bash
terra unified-api destinations create --env <DEV_ID> --type webhook \
  --config '{"url": "https://example.com/terra"}'
```

Creating a webhook destination generates its secret and returns it as `signing_secret` in the `201` response. Retrieving or listing the destination masks it. A dry run returns `will_return_signing_secret: true` instead of a secret, and a replay with the same `Idempotency-Key` returns `signing_secret: null`. In both cases, read the secret from `/secrets`.

## Read a webhook's secret

```http
GET /environments/{dev_id}/unified-api/destinations/{destination_id}/secrets
```

```bash
terra unified-api destinations retrieve-secrets <destination_id> --env <DEV_ID>
```

```json
{
  "id": "1937255512398764032",
  "type": "webhook",
  "secrets": {
    "signing_secret": "a4f8…c917"
  }
}
```

Needs `keys:read`, and every read is audited. `secrets.signing_secret` is `null` for a webhook that has no secret of its own. Deliveries to it are signed with your environment's shared secret until you rotate it. A destination whose stored configuration is unreadable returns `409`.

## Rotate a webhook's secret

```http
POST /environments/{dev_id}/unified-api/destinations/{destination_id}/signing-secret/rotate
```

```bash
terra unified-api destinations rotate-signing-secret <destination_id> --env <DEV_ID>
```

```json
{
  "id": "1937255512398764032",
  "signing_secret": "a4f8…c917"
}
```

Needs `destinations:write` and `keys:write`.

* Every delivery after the call is signed with the new secret, so update your receiver straight away. Other destinations keep theirs.
* `?dry_run=true` returns a preview and generates nothing.
* A replay with the same `Idempotency-Key` returns `signing_secret: null`. Read the secret from `/secrets`.
* A destination that is not a webhook returns `400`. One whose stored configuration is unreadable returns `409`.

## Read the Vantage webhook's secret <a href="#vantage-webhooks" id="vantage-webhooks"></a>

```http
GET /environments/{dev_id}/vantage/webhook/secrets
```

```bash
terra vantage webhook retrieve-secrets --env <DEV_ID>
```

```json
{
  "signing_secret": "correct-horse-battery-staple"
}
```

Needs `keys:read`, and every read is audited. `signing_secret` is `null` while no webhook URL is set. `GET /environments/{dev_id}/vantage/webhook` returns only the URL.

## See also

* [Webhooks](https://docs.tryterra.co/unified-api/integration-setup/setting-up-data-destinations/webhooks)
* [Scopes](https://docs.tryterra.co/reference/admin-api/scopes.md)
