# Tellagen API Reference

> Generated from the same canonical API contract as the human-readable reference at https://tellagen.com/api-reference.

Documentation contract: `sha256:095d1f92210fa831a53b58488bbcfce2078485716295a755cd322d0eb4e2c7fa`. This fingerprint identifies the generated documentation contract, not the API major version.

## Endpoint index

### Webhooks

[Webhooks Markdown export](https://tellagen.com/api-reference/webhooks/markdown)

- [`GET /api/v1/settings/webhooks`](https://tellagen.com/api-reference/webhooks#webhooks-endpoint-get-api-v1-settings-webhooks) — List webhook subscriptions
- [`POST /api/v1/settings/webhooks`](https://tellagen.com/api-reference/webhooks#webhooks-endpoint-post-api-v1-settings-webhooks) — Create a webhook subscription
- [`POST /api/v1/settings/webhooks/{id}/pause`](https://tellagen.com/api-reference/webhooks#webhooks-endpoint-post-api-v1-settings-webhooks-id-pause) — Pause a webhook subscription
- [`POST /api/v1/settings/webhooks/{id}/resume`](https://tellagen.com/api-reference/webhooks#webhooks-endpoint-post-api-v1-settings-webhooks-id-resume) — Resume a webhook subscription
- [`POST /api/v1/settings/webhooks/{id}/revoke`](https://tellagen.com/api-reference/webhooks#webhooks-endpoint-post-api-v1-settings-webhooks-id-revoke) — Revoke a webhook subscription
- [`POST /api/v1/settings/webhooks/{id}/rotate-secret`](https://tellagen.com/api-reference/webhooks#webhooks-endpoint-post-api-v1-settings-webhooks-id-rotate-secret) — Rotate a webhook secret

## Base URL

`https://{company}.api.tellagen.com/api/v1/`

Replace `{company}` with your company subdomain. Requests and JSON responses use `application/json` unless an endpoint documents an empty response.

## Authentication

Create an API token in **Settings > API keys** and send it as a Bearer token:

`Authorization: Bearer tllg_YOUR_TOKEN`

Tokens are shown only once when created. Grant only the scopes the client needs.

## Integration guides

- [Make your first request](https://tellagen.com/api-reference#first-request)
- [Retries and updates](https://tellagen.com/api-reference#reliable-requests)
- [Filter and paginate collections](https://tellagen.com/api-reference/guides/pagination)
- [Create and move an incident through its workflow](https://tellagen.com/api-reference/guides/workflows)
- [Send custom-field values](https://tellagen.com/api-reference/guides/field-values)
- [Receive webhooks (preview)](https://tellagen.com/api-reference/guides/webhooks)

## Versioning

All endpoints in this reference use `/api/v1` and are supported.

**Compatible changes.** Tellagen can add optional response fields or enum values. Ignore response fields that your client does not use.

**Breaking changes.** Tellagen uses a new major version for incompatible changes.

**Deprecated endpoints.** Tellagen marks an endpoint deprecated at least 180 days before removal. Deprecated responses identify the replacement endpoint.

## Scopes

| Scope | Description |
| --- | --- |
| `incidents:read` | List and retrieve incidents, and discover writable workflow statuses and severities |
| `incidents:write` | Create and update incidents and timeline events. Requires an active responder seat for the key owner. |
| `slack_context:read` | Read Slack context collected for incident investigation |
| `services:read` | List and retrieve services, and discover writable service tiers |
| `services:write` | Create, update, and archive services. Requires an active responder seat and the manage_settings role permission. |
| `teams:read` | List and retrieve teams and members |
| `teams:write` | Create, update, and archive teams; manage members. Requires an active responder seat and the manage_teams role permission. |
| `custom_fields:read` | List and retrieve custom field definitions and values |
| `custom_fields:write` | Create, update, and archive custom fields; set incident field values. Definition changes require the manage_settings role permission. Incident value changes require an active responder seat. |
| `webhooks:manage` | Create, pause, resume, revoke, and rotate workspace webhook subscriptions. Requires the manage_settings role permission. |

## Prerequisite definitions

- **Active responder seat** (`active_responder`): The API key owner must have an active responder seat.
- **Manage workspace settings** (`manage_settings`): The API key owner must have the manage_settings role permission.
- **Manage teams** (`manage_teams`): The API key owner must have the manage_teams role permission.
- **Incident is not archived** (`mutable_incident`): The incident must not be archived. Workflow-state restrictions are described by each operation.
- **Linked Slack channel** (`slack_channel`): The incident must have a linked Slack channel.

## Errors

Errors always include a stable `code` and a human-readable `message`. They can also include `field`, `details`, and `request_id`.

You can send `X-Request-ID` with a request. If you omit it, the API generates one. The response header and error body return the same value.

### Missing scope (403)

```json
{
  "code": "missing_scope",
  "message": "insufficient scope: incidents:write required",
  "details": {
    "required_scope": "incidents:write"
  },
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

### Stale resource version (412)

```json
{
  "code": "precondition_failed",
  "message": "the resource changed; fetch it again and retry with the current resource version",
  "field": "If-Tellagen-Resource-Version",
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

### Rate limit (429)

```json
{
  "code": "rate_limited",
  "message": "rate limit exceeded",
  "details": {
    "retry_after_seconds": 1
  },
  "request_id": "01JEXAMPLE8R4N5W6Y7Z"
}
```

When you contact support, include the request ID, method, path, status, and time. Omit tokens and private request bodies.

| Code | Meaning | Next action | Retry |
| --- | --- | --- | --- |
| `authentication_required` | The request has no valid API token or session. | Send an active Bearer token for this workspace. Replace an expired or revoked key. | After correcting authentication. |
| `missing_scope` | The token lacks the scope named in details.required_scope. | Read details.required_scope. Ask a workspace manager for a replacement key with that scope. | After correcting access. |
| `responder_seat_required` | The key owner needs the seat named in details.required_seat. | Ask a workspace manager to review the key owner’s responder seat. | After correcting access. |
| `missing_role_permission` | The key owner lacks details.required_permission or one of details.required_roles. | Ask a workspace manager to review the owner’s role and the permission named in details. | After correcting access. |
| `permission_denied` | Access is denied without exposing private authorization state. | Verify the workspace, key owner, and resource access with a workspace manager. | After correcting access. |
| `invalid_resource_state` | The operation is not valid for the current resource state. | Read the current resource. Restore an archived resource or choose an operation allowed in its current state. | After reconciling state. |
| `invalid_relationship_state` | Restore requires a retained owner or parent relationship to identify an active resource. | Restore the retained parent or owning team before restoring this resource. | After correcting the relationship. |
| `duplicate_slug` | A team already uses the requested slug. | Read the existing team or choose a different slug. | After changing the request. |
| `invalid_json` | The request body is not one valid JSON document. | Send one valid JSON object with Content-Type: application/json. | After correcting the body. |
| `unknown_field` | The request contains an unsupported JSON property named in field. | Remove or correct the property named in field. Use the request schema, not the response schema. | After correcting the body. |
| `request_body_too_large` | The request body is larger than 1 MiB. | Reduce the body to 1 MiB or less. | After reducing the body. |
| `multiple_json_values` | The request body contains more than one JSON document. | Send one JSON document rather than concatenated documents. | After correcting the body. |
| `idempotency_key_reused` | The key was already used with different request content. | Recover the original request for this key. Use a new key only for a different intended operation. | Do not resend changed content with the same key. |
| `idempotency_in_progress` | An equal request with this key is still running. Retry later. | Wait for Retry-After, then resend the identical body with the same key. | After the indicated delay. |
| `idempotency_outcome_unknown` | An earlier request may have completed, but its result could not be stored. Do not retry it automatically. | Read the resource state and contact support with the request ID before deciding whether to create again. | Never retry automatically. |
| `precondition_required` | An API-key PATCH request omitted If-Tellagen-Resource-Version. | Read the resource, then send its Tellagen-Resource-Version as If-Tellagen-Resource-Version. | After adding the current version. |
| `invalid_precondition` | If-Tellagen-Resource-Version is not a positive integer. | Use the positive integer version returned for this resource. Do not use an ETag or a timestamp. | After correcting the header. |
| `precondition_failed` | The resource changed after the client read it. | Read the resource again. Reconcile your intended change with the current state before using its new version. | After reconciling the change. |
| `rate_limited` | Retry after details.retry_after_seconds or the Retry-After header. | Wait for Retry-After or details.retry_after_seconds. Limit concurrency across the workspace. | After the indicated delay, with the original idempotency key where supported. |
| `internal` | The server failed without exposing an internal error. | Keep the request ID. Read current state before retrying a write whose outcome is uncertain. | Retry reads with bounded backoff. Follow operation-specific rules for writes. |
| `invalid_slack_channel_name_request` | The channel-name request is invalid. | Use custom mode with name, or workspace_template mode without name. | After correcting the request. |
| `slack_not_configured` | The workspace has no usable Slack integration. | Ask a workspace manager to connect or repair Slack. | After repairing the integration. |
| `incident_slack_channel_missing` | The incident has no linked Slack channel. | Link a channel through the incident workspace before requesting a rename. | After linking a channel. |
| `slack_channel_not_found` | Slack cannot find the linked channel. | Verify the channel still exists and that the integration can access it. | After repairing channel access. |
| `slack_channel_name_taken` | Another Slack channel uses the requested name. | Choose another custom name or revise the workspace naming template. | After choosing an available name. |
| `invalid_idempotency_key` | The idempotency key has an invalid length or character. | Use 1–128 visible, non-space ASCII characters. A UUID is suitable. | After correcting the key. |

| Status | Meaning |
| --- | --- |
| `400` | Bad Request — invalid input or missing required fields |
| `401` | Unauthorized — missing or invalid token |
| `403` | Forbidden — insufficient scope or responder access |
| `404` | Not Found — resource does not exist |
| `409` | Conflict — resource state prevents the request |
| `412` | Precondition Failed — the supplied resource version is stale |
| `428` | Precondition Required — this operation needs If-Tellagen-Resource-Version |
| `429` | Too Many Requests — rate limit exceeded |
| `500` | Internal Server Error |

Authenticated requests share a workspace limit. Anonymous requests and failed authentication attempts use the trusted client IP. Responses include `X-RateLimit-Limit` and `X-RateLimit-Remaining`. A `429` response also includes `Retry-After`.

## Webhooks

Manage workspace webhook subscriptions and receive signed incident events.

### `GET /api/v1/settings/webhooks`

**List webhook subscriptions.** Lists the webhook subscriptions in the workspace. The response shows the HTTPS scheme and host of each destination. It does not show a signing secret.

This API is in preview. Tellagen can change the webhook event contract before this API becomes supported.


Required scope: `webhooks:manage`

Operation ID: `listWebhookSubscriptions`
Contract: `preview`
Retry guidance: You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts.
Prerequisites: Manage workspace settings

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `webhooks` | `object[]` | Always | The webhook subscriptions in the workspace. |
| `webhooks[].id` | `string` | Always | The webhook subscription ID. |
| `webhooks[].url` | `string` | Always | The HTTPS scheme and host of the destination. Responses omit the path and query string. |
| `webhooks[].event_types` | `string[]` | Always | The event types that the subscription receives. Minimum items: 1. Items must be unique. Possible values: `"incident.created"` |
| `webhooks[].status` | `string` | Always | The delivery state of the subscription. Possible values: `"active"` \| `"paused"` \| `"revoked"` |
| `webhooks[].created_at` | `string (RFC 3339)` | Always | The time when the subscription was created. |
| `webhooks[].updated_at` | `string (RFC 3339)` | Always | The time when the subscription last changed. |
| `webhooks[].last_success_at` | `string (RFC 3339) \| null` | Always | The time of the most recent successful delivery. The value is null before a successful delivery. |
| `webhooks[].last_failure_at` | `string (RFC 3339) \| null` | Always | The time of the most recent failed delivery. The value is null before a failed delivery. |

Returns all webhook subscriptions in the workspace.

```json
{
  "webhooks": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "url": "https://hooks.example.test",
      "event_types": [
        "incident.created"
      ],
      "status": "active",
      "created_at": "2026-09-14T10:00:00Z",
      "updated_at": "2026-09-14T10:00:00Z",
      "last_success_at": null,
      "last_failure_at": null
    }
  ]
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/settings/webhooks`

**Create a webhook subscription.** Creates a webhook subscription for the workspace. Use an HTTPS URL that resolves to a public address. The API returns the signing secret once.

If event_types is omitted, the API sends incident.created events. This API is in preview. Tellagen can change the webhook event contract before this API becomes supported.


Required scope: `webhooks:manage`

Operation ID: `createWebhookSubscription`
Contract: `preview`
Retry guidance: If the result is unknown, read the resource before another attempt. The error details explain the next step.
Prerequisites: Manage workspace settings

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://hooks.example.test/tellagen",
  "event_types": [
    "incident.created"
  ]
}'
```

#### Request body

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Yes | An absolute HTTPS URL that resolves to a public address. Maximum length: 2048 characters. |
| `event_types` | `string[]` | No | The event types to send. If omitted, the API sends incident.created. Minimum items: 1. Items must be unique. Allowed values: `"incident.created"` |

Request JSON:

```json
{
  "url": "https://hooks.example.test/tellagen",
  "event_types": [
    "incident.created"
  ]
}
```

#### Success response

Status: `201 Created`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `webhook` | `object` | Always | A workspace webhook subscription. |
| `webhook.id` | `string` | Always | The webhook subscription ID. |
| `webhook.url` | `string` | Always | The HTTPS scheme and host of the destination. Responses omit the path and query string. |
| `webhook.event_types` | `string[]` | Always | The event types that the subscription receives. Minimum items: 1. Items must be unique. Possible values: `"incident.created"` |
| `webhook.status` | `string` | Always | The delivery state of the subscription. Possible values: `"active"` \| `"paused"` \| `"revoked"` |
| `webhook.created_at` | `string (RFC 3339)` | Always | The time when the subscription was created. |
| `webhook.updated_at` | `string (RFC 3339)` | Always | The time when the subscription last changed. |
| `webhook.last_success_at` | `string (RFC 3339) \| null` | Always | The time of the most recent successful delivery. The value is null before a successful delivery. |
| `webhook.last_failure_at` | `string (RFC 3339) \| null` | Always | The time of the most recent failed delivery. The value is null before a failed delivery. |
| `secret` | `string` | Optional | The signing secret. The API returns this field only after create or secret rotation. |

Returns the created subscription and its signing secret. The secret appears only in this response.

```json
{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "active",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:00:00Z",
    "last_success_at": null,
    "last_failure_at": null
  },
  "secret": "whsec_example_secret_value"
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/settings/webhooks/{id}/pause`

**Pause a webhook subscription.** Stops new deliveries for the subscription. Existing delivery records remain available for the worker and the subscription stays available for later resume.

Required scope: `webhooks:manage`

Operation ID: `pauseWebhookSubscription`
Contract: `preview`
Retry guidance: If the result is unknown, read the resource before another attempt. The error details explain the next step.
Prerequisites: Manage workspace settings

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | A webhook subscription ID returned by this API. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/pause' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `webhook` | `object` | Always | A workspace webhook subscription. |
| `webhook.id` | `string` | Always | The webhook subscription ID. |
| `webhook.url` | `string` | Always | The HTTPS scheme and host of the destination. Responses omit the path and query string. |
| `webhook.event_types` | `string[]` | Always | The event types that the subscription receives. Minimum items: 1. Items must be unique. Possible values: `"incident.created"` |
| `webhook.status` | `string` | Always | The delivery state of the subscription. Possible values: `"active"` \| `"paused"` \| `"revoked"` |
| `webhook.created_at` | `string (RFC 3339)` | Always | The time when the subscription was created. |
| `webhook.updated_at` | `string (RFC 3339)` | Always | The time when the subscription last changed. |
| `webhook.last_success_at` | `string (RFC 3339) \| null` | Always | The time of the most recent successful delivery. The value is null before a successful delivery. |
| `webhook.last_failure_at` | `string (RFC 3339) \| null` | Always | The time of the most recent failed delivery. The value is null before a failed delivery. |
| `secret` | `string` | Optional | The signing secret. The API returns this field only after create or secret rotation. |

Returns the paused subscription.

```json
{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "paused",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:02:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/settings/webhooks/{id}/resume`

**Resume a webhook subscription.** Starts new deliveries for a paused subscription. A revoked subscription cannot resume.

Required scope: `webhooks:manage`

Operation ID: `resumeWebhookSubscription`
Contract: `preview`
Retry guidance: If the result is unknown, read the resource before another attempt. The error details explain the next step.
Prerequisites: Manage workspace settings

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | A webhook subscription ID returned by this API. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/resume' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `webhook` | `object` | Always | A workspace webhook subscription. |
| `webhook.id` | `string` | Always | The webhook subscription ID. |
| `webhook.url` | `string` | Always | The HTTPS scheme and host of the destination. Responses omit the path and query string. |
| `webhook.event_types` | `string[]` | Always | The event types that the subscription receives. Minimum items: 1. Items must be unique. Possible values: `"incident.created"` |
| `webhook.status` | `string` | Always | The delivery state of the subscription. Possible values: `"active"` \| `"paused"` \| `"revoked"` |
| `webhook.created_at` | `string (RFC 3339)` | Always | The time when the subscription was created. |
| `webhook.updated_at` | `string (RFC 3339)` | Always | The time when the subscription last changed. |
| `webhook.last_success_at` | `string (RFC 3339) \| null` | Always | The time of the most recent successful delivery. The value is null before a successful delivery. |
| `webhook.last_failure_at` | `string (RFC 3339) \| null` | Always | The time of the most recent failed delivery. The value is null before a failed delivery. |
| `secret` | `string` | Optional | The signing secret. The API returns this field only after create or secret rotation. |

Returns the active subscription.

```json
{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "active",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:03:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/settings/webhooks/{id}/revoke`

**Revoke a webhook subscription.** Revokes a webhook subscription and cancels its pending deliveries. A revoked subscription cannot resume.

Required scope: `webhooks:manage`

Operation ID: `revokeWebhookSubscription`
Contract: `preview`
Retry guidance: If the result is unknown, read the resource before another attempt. The error details explain the next step.
Prerequisites: Manage workspace settings

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | A webhook subscription ID returned by this API. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/revoke' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `webhook` | `object` | Always | A workspace webhook subscription. |
| `webhook.id` | `string` | Always | The webhook subscription ID. |
| `webhook.url` | `string` | Always | The HTTPS scheme and host of the destination. Responses omit the path and query string. |
| `webhook.event_types` | `string[]` | Always | The event types that the subscription receives. Minimum items: 1. Items must be unique. Possible values: `"incident.created"` |
| `webhook.status` | `string` | Always | The delivery state of the subscription. Possible values: `"active"` \| `"paused"` \| `"revoked"` |
| `webhook.created_at` | `string (RFC 3339)` | Always | The time when the subscription was created. |
| `webhook.updated_at` | `string (RFC 3339)` | Always | The time when the subscription last changed. |
| `webhook.last_success_at` | `string (RFC 3339) \| null` | Always | The time of the most recent successful delivery. The value is null before a successful delivery. |
| `webhook.last_failure_at` | `string (RFC 3339) \| null` | Always | The time of the most recent failed delivery. The value is null before a failed delivery. |
| `secret` | `string` | Optional | The signing secret. The API returns this field only after create or secret rotation. |

Returns the revoked subscription.

```json
{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "revoked",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:04:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |

### `POST /api/v1/settings/webhooks/{id}/rotate-secret`

**Rotate a webhook secret.** Creates a new signing secret for the subscription. The API returns the new secret once.

Tellagen signs deliveries with the new secret and the previous secret for 24 hours. Update the receiver during this period.


Required scope: `webhooks:manage`

Operation ID: `rotateWebhookSecret`
Contract: `preview`
Retry guidance: If the result is unknown, read the resource before another attempt. The error details explain the next step.
Prerequisites: Manage workspace settings

#### Path parameters

Required nested fields apply when their parent object is present. Optional does not imply nullable.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | Yes | A webhook subscription ID returned by this API. |

#### Example request

Replace `{company}`, `<token>`, and any other placeholders with your values.

```bash
curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/rotate-secret' \
  --header 'Authorization: Bearer <token>'
```

#### Success response

Status: `200 OK`

#### Response fields

Returned means the field is present when its parent object is present. A nullable field can contain null.

| Name | Type | Returned | Description |
| --- | --- | --- | --- |
| `webhook` | `object` | Always | A workspace webhook subscription. |
| `webhook.id` | `string` | Always | The webhook subscription ID. |
| `webhook.url` | `string` | Always | The HTTPS scheme and host of the destination. Responses omit the path and query string. |
| `webhook.event_types` | `string[]` | Always | The event types that the subscription receives. Minimum items: 1. Items must be unique. Possible values: `"incident.created"` |
| `webhook.status` | `string` | Always | The delivery state of the subscription. Possible values: `"active"` \| `"paused"` \| `"revoked"` |
| `webhook.created_at` | `string (RFC 3339)` | Always | The time when the subscription was created. |
| `webhook.updated_at` | `string (RFC 3339)` | Always | The time when the subscription last changed. |
| `webhook.last_success_at` | `string (RFC 3339) \| null` | Always | The time of the most recent successful delivery. The value is null before a successful delivery. |
| `webhook.last_failure_at` | `string (RFC 3339) \| null` | Always | The time of the most recent failed delivery. The value is null before a failed delivery. |
| `secret` | `string` | Optional | The signing secret. The API returns this field only after create or secret rotation. |

Returns the subscription and the new signing secret. The secret appears only in this response.

```json
{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "active",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:05:00Z",
    "last_success_at": null,
    "last_failure_at": null
  },
  "secret": "whsec_new_example_secret_value"
}
```

#### Endpoint error responses

| Status | Meaning |
| --- | --- |
| `400` | The API rejected the request because its syntax or one of its values is invalid. |
| `401` | The request does not contain valid authentication. |
| `403` | Authentication succeeded, but the caller lacks the required API scope or workspace permission. |
| `404` | The requested resource does not exist or is not available to the caller. |
| `409` | The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically. |
| `429` | The workspace exceeded an active request limit. |
| `500` | An internal server error prevented completion of the request. |