> ## Documentation Index > Fetch the complete documentation index at: https://docs.tavrn.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rotate secret > Issue a new signing secret. The response is the only time the new secret is shown. For 24 hours every delivery is signed with both secrets (`X-Tavrn-Signature-V1: v1=,v1=`), so update your verifier any time inside that window. Requires `webhooks:write`. No request body. ## OpenAPI ````yaml POST /v2/webhooks/{id}/rotate-secret openapi: 3.1.0 info: title: Tavrn Platform API version: '2026-10-16' description: >- Enterprise API for medical record retrieval: cases, retrieval requests, retrieved records and provider invoices, case documents, and webhook notifications. Behaviour is versioned by date via the Tavrn-Version header (see Guides > Versioning); the path stays /v2. contact: name: Tavrn Support email: contact@tavrn.ai servers: - url: https://enterprise.tavrn.ai description: Production server security: - bearerAuth: [] tags: - name: Cases description: Case management operations - name: Documents description: Document upload and management - name: Retrieval Requests description: Medical record retrieval requests submitted to healthcare facilities - name: Requestors description: Multiple retrieval profiles within one organization - name: Webhooks description: Webhook registration and event notifications - name: Events description: Persisted log of every event Tavrn emitted for your organization paths: /v2/webhooks/{id}/rotate-secret: post: tags: - Webhooks summary: Rotate secret description: >- Issue a new signing secret. The response is the only time the new secret is shown. For 24 hours every delivery is signed with both secrets (`X-Tavrn-Signature-V1: v1=,v1=`), so update your verifier any time inside that window. Requires `webhooks:write`. No request body. operationId: rotateWebhookSecret parameters: - name: id in: path required: true description: Webhook ID schema: type: string - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: New secret issued headers: Request-Id: $ref: '#/components/headers/RequestId' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/WebhookSecretRotation' '404': description: >- Not found. Ids that belong to another organization are indistinguishable from unknown ids. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Webhook not found '409': description: >- Another rotation completed concurrently; retry Also returned as `idempotency_key_in_use` when the `Idempotency-Key` is still being processed by an earlier request. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: conflict message: Webhook secret was rotated concurrently; retry '422': description: >- The `Idempotency-Key` was already used with a different request payload (`idempotency_key_reused_with_different_payload`). Use a new key for a new request. content: application/json: schema: $ref: '#/components/schemas/Error' '500': $ref: '#/components/responses/InternalError' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional opaque key (1-255 characters, a UUID v4 is recommended) that makes a POST safe to retry. Scoped to your organization and kept for 24 hours. A retry with the same key and the same body replays the original status and body with `Idempotent-Replayed: true`; the same key with a different body returns `422 idempotency_key_reused_with_different_payload`; a retry while the first attempt is still running returns `409 idempotency_key_in_use`. Only 2xx and 4xx outcomes are stored - a 5xx releases the key so the retry executes again. See the [Idempotent requests](/guides/v2/idempotency) guide. schema: type: string minLength: 1 maxLength: 255 example: 7f1c3b58-2a2d-4b31-9c0e-6a7f0b8d2e11 headers: RequestId: description: >- Unique id for this request (`req_…`, or the `Request-Id` / `X-Request-Id` you sent, when printable ASCII and at most 128 characters). Present on every /v2 response; quote it in support requests. schema: type: string maxLength: 128 example: req_0c1f1f1cd1c84e2f8d4b6a2e9f3b7a11 IdempotentReplayed: description: >- Present (value `true`) only when this response was replayed from a previous request that carried the same `Idempotency-Key`. schema: type: string enum: - 'true' schemas: WebhookSecretRotation: type: object required: - id - secret - secret_hint - previous_secret_expires_at properties: id: type: string secret: type: string description: New signing secret. Returned only in this response. example: whsec_… secret_hint: type: string example: ...abc1 previous_secret_expires_at: type: string format: date-time description: Until this time deliveries are also signed with the previous secret Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Machine-readable error code example: validation_error message: type: string description: Human-readable error message example: The patient.date_of_birth field is required param: type: string description: Field the error refers to, when applicable example: patient.date_of_birth request_id: type: string description: Same value as the `Request-Id` response header example: req_0c1f1f1cd1c84e2f8d4b6a2e9f3b7a11 doc_url: type: string format: uri description: Link to this error code in the error reference example: https://docs.tavrn.ai/guides/v2/errors#validation_error responses: InternalError: description: >- Tavrn failed to process the request (`internal_error`). Retry with backoff; if it persists, contact support quoting the `Request-Id`. headers: Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: Internal server error request_id: req_0c1f1f1cd1c84e2f8d4b6a2e9f3b7a11 doc_url: https://docs.tavrn.ai/guides/v2/errors#internal_error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API key authentication. Use format: `Authorization: Bearer tavrn_sk_live_...` ````