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

# Rotate Webhook Secret

> Rotate the HMAC signing secret for a webhook endpoint. The new secret is returned once.



## OpenAPI

````yaml POST /api/v1/webhooks/{endpointID}/rotate-secret
openapi: 3.1.0
info:
  title: Nexio API
  version: '1.0'
  description: |
    Nexio agentic infrastructure API. Configure engines for placement,
    entity analysis, and other patterns. Submit runs, poll for results,
    or subscribe to signed webhook callbacks.
  contact:
    email: support@usenexio.com
    url: https://docs.usenexio.com
servers:
  - url: https://api.usenexio.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: EngineManagement
    description: Create, configure, and manage inference engines.
  - name: Engines
    description: Engine-scoped endpoints for submitting runs and retrieving results.
  - name: Runs
    description: Retrieve and reconcile submitted runs.
  - name: Catalog
    description: >-
      Read current carriers and products extracted for the authenticated
      organization.
  - name: Environments
    description: Isolated tenancy scopes under your org (one live plus non-live sandboxes).
  - name: Webhooks
    description: Manage webhook endpoints for push-based delivery of terminal run events.
paths:
  /api/v1/webhooks/{endpointID}/rotate-secret:
    post:
      tags:
        - Webhooks
      summary: Rotate Webhook Secret
      description: |
        Generate a new signing secret for the endpoint. The previous secret
        remains valid according to a server-owned environment policy: 24 hours
        for `live-v1` and five minutes for `sandbox-v1`. The response identifies
        the policy and exact expiration. Callers cannot set the overlap.

        During the overlap window, deliveries include multiple `v1=` values in
        the `X-Nexio-Signature` header: one for each active secret.
      operationId: rotateWebhookSecret
      parameters:
        - $ref: '#/components/parameters/EndpointID'
      responses:
        '200':
          description: New secret generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotateSecretResponse'
              example:
                id: 550e8400-e29b-41d4-a716-446655440000
                secret: whsec_newkey789
                rotation_policy_id: live-v1
                previous_secret_expires_at: '2026-03-23T12:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/AuthUnavailable'
components:
  parameters:
    EndpointID:
      name: endpointID
      in: path
      required: true
      description: Webhook endpoint UUID.
      schema:
        type: string
        format: uuid
  schemas:
    RotateSecretResponse:
      type: object
      additionalProperties: false
      required:
        - id
        - secret
        - rotation_policy_id
      properties:
        id:
          type: string
          format: uuid
          description: Endpoint identifier.
        secret:
          type: string
          description: New signing secret (`whsec_...`). Displayed only once.
        rotation_policy_id:
          type: string
          enum:
            - live-v1
            - sandbox-v1
          description: '`live-v1` overlaps for 24 hours; `sandbox-v1` for five minutes.'
        previous_secret_expires_at:
          type: string
          format: date-time
          description: Exact instant when the previous secret stops being valid.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Stable snake_case error identifier. Safe to match programmatically.

            Known codes: `invalid_request`, `invalid_input`, `unauthorized`,
            `auth_unavailable`, `rate_limited`, `missing_run_id`,
            `invalid_run_id`, `run_not_found`, `invalid_offerings`,
            `missing_input`, `queue_unreachable`,
            `engine_not_found`, `engine_slug_conflict`, `engine_archived`,
            `invalid_engine_type`, `validation_error`,
            `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`,
            `invalid_events`, `invalid_description`, `invalid_auth_token`,
            `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`,
            `invalid_delivery_id`, `delivery_not_found`,
            `delivery_not_resendable`, `insufficient_capability`,
            `engine_version_required`, `engine_version_exact_required`,
            `engine_version_not_found`, `engine_version_invalid_format`,
            `engine_version_draft_requires_sandbox_key`,
            `engine_version_none_released`, `test_scenario_sandbox_only`,
            `test_scenario_forbidden`, `test_scenario_exact_version_required`,
            `test_scenario_version_not_supported`, `invalid_test_scenario`,
            `request_bound_exceeded`, and `run_cap_exceeded`.
        message:
          type: string
          description: Human-readable error message. May change between versions.
        details:
          description: |
            Optional request-specific details. Request-bound failures use the
            `RequestBoundDetails` object. Validation failures may use an array
            of field issues or another documented object.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key
    WebhookNotFound:
      description: Webhook endpoint not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: webhook_not_found
            message: Webhook endpoint not found
    RateLimited:
      description: Rate limit exceeded. Retry after the window resets.
      headers:
        Retry-After:
          description: Seconds until the rate limit window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limited
            message: Rate limit exceeded
    AuthUnavailable:
      description: API key authentication is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: auth_unavailable
            message: API key authentication is temporarily unavailable
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Send the credential as `Authorization: Bearer <key>`.

        Scoped partner credentials use the exclusive `nxsk_v1_...` namespace.
        Each scoped key is bound at issuance to one organization, one canonical
        named environment, an explicit engine set, and a least-privilege
        capability set. A malformed, unknown, rotated, or revoked `nxsk_` key
        fails closed and is never retried as a legacy key.

        Capabilities used by this API are `runs:write`, `runs:read`,
        `engines:read`, `catalog:read`, `webhooks:manage`,
        `runs:defensibility:read`, `runs:test`, and `converse:use`. Operation
        descriptions name the required capability.
        Grandfathered `nx_live_...` and `nx_test_...` keys retain their existing
        broad access during the compatibility window.

````