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

# Rotate your webhook signing secret

> Replace the webhook signing secret. The old one keeps signing deliveries for 24 hours so you can switch over.

Rotate the secret if it may have leaked, or as routine hygiene. You get the new secret in the response.

For the next 24 hours every delivery is signed with **both** secrets, new first:

```http theme={null}
X-Valendata-Signature: v1=<signed with new secret>,v1=<signed with old secret>
```

`previous_valid_until` in the response says when the old one stops. Update your receiver to the new secret before then. A receiver that splits the header on commas and accepts any match keeps working the whole time.

Rotating with an API key needs the `webhooks:write` scope. You can also rotate from **Settings → API Keys** in the app.


## OpenAPI

````yaml POST /v1/webhooks/secret/rotate
openapi: 3.0.3
info:
  title: Valendata REST API
  version: 1.0.0
  description: >-
    Trigger Skills, manage Workflows, retrieve Runs, and stream structured
    results from any language using JSON over HTTPS.
servers:
  - url: https://api.valendata.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Skills
    description: Execute and inspect published Skills.
  - name: Workflows
    description: Trigger multi-step Workflows and list them.
  - name: Runs
    description: Start async Skill runs and read Skill and Workflow run results.
  - name: Skill creation
    description: Create a Skill from a plain-language task.
  - name: Skill improvement
    description: >-
      Fix a Skill, add fields to it or re-learn its detail steps, poll the
      result, and read its change history.
  - name: Versions
    description: List, diff, restore, and pin a Skill's recipe versions.
  - name: Webhooks
    description: Signed delivery of finished async runs.
paths:
  /v1/webhooks/secret/rotate:
    post:
      tags:
        - Webhooks
      summary: Rotate your webhook signing secret
      description: >-
        Replace the signing secret with a new random one and return it. The
        previous secret keeps signing deliveries (as a second comma-separated
        `v1=` value) until `previous_valid_until`, 24 hours from now. Needs the
        `webhooks:write` scope when called with an API key.
      operationId: rotateWebhookSecret
      responses:
        '200':
          description: The new signing secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSecret'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    WebhookSecret:
      type: object
      properties:
        secret:
          type: string
          description: Your signing secret. Keep it private.
        signature_header:
          type: string
          example: X-Valendata-Signature
        algorithm:
          type: string
          example: HMAC-SHA256 over '<timestamp>.<raw body>'
        previous_valid_until:
          type: string
          format: date-time
          nullable: true
          description: >-
            Set for 24 hours after a rotation: until then deliveries are also
            signed with the previous secret.
        rotated_at:
          type: string
          format: date-time
          nullable: true
          description: When the secret was last rotated.
    Error:
      type: object
      properties:
        detail:
          oneOf:
            - type: string
            - type: object
              additionalProperties: true
          description: >-
            Error message. Usually a plain string; may be a structured object
            for some errors.
      example:
        detail: Invalid or expired API key
  responses:
    Unauthorized:
      description: >-
        Unauthorized. The Authorization header is missing, malformed, or the
        credential is invalid or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Forbidden. You may not run or change this Skill, or it is not published
        or active.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: vd_sk_...
      description: >-
        API key with the `vd_sk_` prefix. Create keys from Settings, API Keys in
        the dashboard.

````

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