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

# Rotate a webhook endpoint's signing secret

> Issues a new signing secret for the endpoint, returned exactly once. With mode graceful (the default) the previous secret keeps verifying for 24 hours (previous_secret_invalid_at in the response) so the new secret can be rolled out across a deploy without dropping deliveries in flight. With mode immediate the previous secret stops verifying at once, for a secret that may be compromised. A missing or wrong-organization id returns 404.

<span class="api-role api-role-admin" title="Admins only.">Minimum role required: Admin</span>


## OpenAPI

````yaml /api-reference/openapi-backend.json post /webhooks/endpoints/{endpoint_id}:rotateSecret
openapi: 3.1.0
info:
  description: Axilio backend HTTP API.
  title: Axilio API
  version: 0.107.0
servers:
  - url: https://api.axilio.ai/api/v1
    description: Production
security: []
tags:
  - name: API Keys
  - name: Billing
  - name: Files
  - name: Organization
  - name: Phones
  - name: Runs
  - name: Skill
  - name: Usage
  - name: Webhooks
  - name: Workflows
paths:
  /webhooks/endpoints/{endpoint_id}:rotateSecret:
    post:
      tags:
        - Webhooks
      summary: Rotate a webhook endpoint's signing secret
      description: >-
        Issues a new signing secret for the endpoint, returned exactly once.
        With mode graceful (the default) the previous secret keeps verifying for
        24 hours (previous_secret_invalid_at in the response) so the new secret
        can be rolled out across a deploy without dropping deliveries in flight.
        With mode immediate the previous secret stops verifying at once, for a
        secret that may be compromised. A missing or wrong-organization id
        returns 404.
      operationId: webhooks_rotate_endpoint_secret
      parameters:
        - description: Endpoint identifier.
          in: path
          name: endpoint_id
          required: true
          schema:
            description: Endpoint identifier.
            minLength: 1
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRotateSecretRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookRotateSecretResponse'
          description: OK
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/V2ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/V2ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/V2ErrorModel'
          description: Internal Server Error
      security:
        - apiKeyAuth: []
components:
  schemas:
    WebhookRotateSecretRequest:
      additionalProperties: false
      description: >-
        Optional body for rotating a signing secret: how the previous secret is
        retired.
      properties:
        mode:
          description: >-
            graceful: the previous secret keeps verifying for 24 hours so the
            new one can be rolled out across a deploy. immediate: the previous
            secret stops verifying at once, for a secret that may be
            compromised. Omit for graceful.
          enum:
            - graceful
            - immediate
          type: string
      type: object
    WebhookRotateSecretResponse:
      additionalProperties: false
      description: >-
        A rotated signing secret, shown once, with the grace window during which
        the old secret still verifies.
      properties:
        id:
          description: Endpoint identifier.
          type: string
        previous_secret_invalid_at:
          description: >-
            When the previous signing secret stops verifying: 24 hours out for a
            graceful rotation, already past for an immediate one. Until then
            both the old and new secret verify.
          format: date-time
          type: string
        secret:
          description: >-
            New Standard Webhooks signing secret (whsec_...). Shown once and
            never returned again.
          type: string
      required:
        - id
        - secret
      type: object
    V2ErrorModel:
      additionalProperties: false
      description: >-
        Error response, following RFC 9457 (Problem Details for HTTP APIs).
        Returned with a application/problem+json content type.
      properties:
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/V2ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    V2ErrorDetail:
      additionalProperties: false
      description: >-
        One specific problem within an error response, locating the offending
        part of the request.
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    apiKeyAuth:
      description: Customer API key (axl_ prefix).
      in: header
      name: X-Axilio-Api-Key
      type: apiKey

````

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