> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telleo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate the signing secret

> Replaces the signing secret and returns the new one once. Deliveries are signed with the new secret straight away, so update your server first or accept both secrets for a few minutes.

Scope: `webhooks:manage`.



## OpenAPI

````yaml /api-reference/openapi.json post /webhook/rotate-secret
openapi: 3.1.0
info:
  title: Telleo API
  version: 1.0.0
  description: Start AI phone calls from your own systems and get each call's outcome back.
servers:
  - url: https://api.telleo.ai/v1
security:
  - ApiKey: []
tags:
  - name: Calls
  - name: Batches
  - name: Agents
  - name: Webhook
paths:
  /webhook/rotate-secret:
    post:
      tags:
        - Webhook
      summary: Rotate the signing secret
      description: >-
        Replaces the signing secret and returns the new one once. Deliveries are
        signed with the new secret straight away, so update your server first or
        accept both secrets for a few minutes.


        Scope: `webhooks:manage`.
      operationId: rotateWebhookSecret
      responses:
        '200':
          description: The webhook with its new `secret`.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: The key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_api_key:
                  value:
                    error:
                      code: missing_api_key
                      message: Send your API key in the X-API-Key header.
                      request_id: req_8f2c1a7e
                invalid_api_key:
                  value:
                    error:
                      code: invalid_api_key
                      message: This API key is not valid.
                      request_id: req_8f2c1a7e
        '404':
          description: No webhook with this id belongs to your account.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  value:
                    error:
                      code: not_found
                      message: Webhook not found.
                      request_id: req_8f2c1a7e
        '429':
          description: Too many requests for this key.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rate_limited:
                  value:
                    error:
                      code: rate_limited
                      message: Too many requests. Retry after 12 seconds.
                      request_id: req_8f2c1a7e
components:
  headers:
    RequestId:
      schema:
        type: string
      description: Unique id of this request. Quote it to support.
  schemas:
    Webhook:
      type: object
      properties:
        object:
          type: string
          const: webhook
        url:
          type: string
        enabled:
          type: boolean
        events:
          type: array
          items:
            type: string
          example:
            - call.completed
            - call.not_connected
        secret:
          type: string
          description: >-
            The signing secret. Returned only when the endpoint is first set and
            when the secret is rotated. Store it.
          example: whsec_3f9a…
        secret_hint:
          type: string
          description: First and last characters of the secret, on reads.
          example: whsec_…9c1d
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable code. Branch on this, not on the message.
              example: invalid_request
            message:
              type: string
              description: A sentence you can log or show to an operator.
            request_id:
              type: string
              description: Quote this when you contact support.
            details:
              type: object
              additionalProperties: true
              description: >-
                Extra context, e.g. `errors: [{field, message}]` for validation
                errors or `call_id` for conflicts.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your AI calling API key (`vak_call_…`). `Authorization: Bearer <key>`
        also works.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.