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

# Set Signing Secret

> Generate or replace the secret used to sign webhook deliveries.

Generates a signing secret for an existing webhook, or replaces it with the `signing_secret` you supply. A supplied secret must contain at least 16 characters. The secret is returned once in `data.signing_secret`; store it securely, since it cannot be read back.

Rotation takes effect immediately. If you supply your own secret, configure your receiver to accept it before making this call. See [Secret rotation](/essentials/v2/webhooks#manage-the-signing-secret).

```python Python SDK theme={"dark"}
result = client.webhooks.set_signing_secret()
secret = result.data.signing_secret
```

```typescript TypeScript SDK theme={"dark"}
const result = await client.webhooks.setSigningSecret();
const secret = result.data?.signingSecret;
```

```bash cURL theme={"dark"}
curl -X POST 'https://api.hydradb.com/webhooks/indexing/signing-secret' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"
```

To enable signing when creating a webhook, use `generate_signing_secret: true` on [Register Webhook](/api-reference/v2/endpoint/register-webhook). If no webhook is registered, this endpoint returns `404`.

## Related resources

* [Webhooks guide](/essentials/v2/webhooks): verify signatures on your receiver
* [Send Test Delivery](/api-reference/v2/endpoint/test-webhook): check signature verification
* [Disable Signing](/api-reference/v2/endpoint/disable-webhook-signing): remove the secret


## OpenAPI

````yaml api-reference/v2/openapi.json POST /webhooks/indexing/signing-secret
openapi: 3.1.0
info:
  contact:
    email: support@hydradb.com
    name: HydraDB Support
  description: >-
    The HydraDB API: ingest context, query it, and manage databases, connectors
    and webhooks.
  license:
    name: Proprietary
  title: HydraDB Application API
  version: 0.1.0
servers:
  - description: Production server
    url: https://api.hydradb.com
security: []
externalDocs:
  description: ''
  url: ''
paths:
  /webhooks/indexing/signing-secret:
    post:
      tags:
        - webhooks
      summary: Generate or set the webhook signing secret
      description: Set or generate the secret used to sign webhook deliveries.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhooks.SigningSecretRequest'
        description: Omit the body to have a secret generated for you
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/handler.Envelope-webhooks_SigningSecretResponse
          description: OK
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Not Found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Unprocessable Entity
      security:
        - BearerAuth: []
components:
  schemas:
    webhooks.SigningSecretRequest:
      properties:
        signing_secret:
          description: >-
            Secret for signing webhook deliveries, at least 16 characters. Omit
            it or send null to generate one.
          example: whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY
          type: string
      type: object
    handler.Envelope-webhooks_SigningSecretResponse:
      properties:
        data:
          $ref: '#/components/schemas/webhooks.SigningSecretResponse'
          example:
            generated: true
            message: Success
            signing_secret: whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY
        error:
          anyOf:
            - $ref: '#/components/schemas/handler.apiError'
              title: Error details
            - title: No error
              type: 'null'
          description: Error details on failure, or null on success.
          example: null
        meta:
          $ref: '#/components/schemas/handler.responseMeta'
          example:
            collection: team_docs
            database: acme_corp
            latency_ms: 12.3
            request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
            source_type: file
            sub_tenant_id: sub_tenant_4567
            tenant_id: tenant_1234
        success:
          description: Whether the request succeeded.
          example: true
          type: boolean
      type: object
    handler.ErrorResponse:
      properties:
        data:
          description: Always `null` on this error response.
        detail:
          $ref: '#/components/schemas/handler.ErrorDetail'
          description: Structured error detail with code, message, and deprecation hints.
          example:
            deprecated: true
            deprecated_field: tenant_id
            error_code: VALIDATION_ERROR
            message: Request validation failed
            preferred_field: database
        error:
          $ref: '#/components/schemas/handler.apiError'
          description: Error message, empty string on success.
          example:
            code: DATABASE_NOT_FOUND
            message: Database not found
        meta:
          $ref: '#/components/schemas/handler.ErrorMeta'
          example:
            latency_ms: 12.3
            request_id: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
        success:
          description: Whether the request succeeded.
          example: false
          type: boolean
      type: object
    webhooks.SigningSecretResponse:
      properties:
        generated:
          description: >-
            Whether the returned secret was generated by HydraDB rather than
            supplied by you.
          example: true
          type: boolean
        message:
          description: Human-readable result message.
          example: Success
          type: string
        signing_secret:
          description: Signing secret. Store it securely to verify webhook deliveries.
          example: whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY
          type: string
      type: object
    handler.apiError:
      properties:
        code:
          description: Machine-readable error code (e.g. `DATABASE_NOT_FOUND`).
          example: DATABASE_NOT_FOUND
          type: string
        details:
          additionalProperties:
            type: string
          description: >-
            Extra facts about the error, as string pairs. Omitted when there are
            none.
          type: object
        message:
          description: Human-readable description of the error.
          example: Database not found
          type: string
        param:
          description: >-
            The request field that caused the error. Omitted when no single
            field is at fault.
          type: string
      type: object
    handler.responseMeta:
      properties:
        api_version:
          description: >-
            Version of the API that served the request, for example `2.0.1`.
            Always present.
          type: string
        collection:
          description: >-
            Collection scope. Defaults to the default collection when omitted.
            Formerly `sub_tenant_id`; the `sub_tenant_id` alias is still
            accepted (deprecated).
          example: team_docs
          type: string
        database:
          description: >-
            Owning database. Formerly `tenant_id`; the `tenant_id` alias is
            still accepted (deprecated).
          example: acme_corp
          type: string
        deprecation:
          description: >-
            Migration notices for this request, present only when it used a
            deprecated route, field or selector. The status code is unaffected.
          items:
            $ref: '#/components/schemas/handler.deprecationNotice'
          type: array
          uniqueItems: false
        latency_ms:
          description: Server-side processing time in milliseconds.
          example: 12.3
          type:
            - number
            - 'null'
        request_id:
          description: Unique identifier for this request, useful for support and tracing.
          example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
          type: string
        source_type:
          description: Type of the parent source (e.g. `file`, `slack`, `notion`).
          example: file
          type: string
        sub_tenant_id:
          deprecated: true
          description: 'Deprecated: use `collection`.'
          example: sub_tenant_4567
          type: string
          x-deprecated: 'true'
        tenant_id:
          deprecated: true
          description: 'Deprecated: use `database`.'
          example: tenant_1234
          type: string
          x-deprecated: 'true'
      type: object
    handler.ErrorDetail:
      properties:
        deprecated:
          description: Whether this response concerns a deprecated field or route.
          example: true
          type: boolean
        deprecated_field:
          description: The deprecated field name.
          example: tenant_id
          type: string
        error_code:
          description: Machine-readable error classification code.
          example: VALIDATION_ERROR
          type: string
        message:
          description: Human-readable description of the error.
          example: Request validation failed
          type: string
        preferred_field:
          description: The canonical replacement for the deprecated field.
          example: database
          type: string
        success:
          deprecated: true
          description: >-
            Deprecated: always `false`. Read the HTTP status, then `error.code`
            and `error.message`.
          example: false
          type: boolean
          x-deprecated: 'true'
      type: object
    handler.ErrorMeta:
      properties:
        api_version:
          description: Version of the API that served the request, for example `2.0.1`.
          type: string
        latency_ms:
          description: Server-side processing time in milliseconds.
          example: 12.3
          type: number
        request_id:
          description: Unique identifier for this request, useful for support and tracing.
          example: 9d13aef4-02f4-4e73-8c62-4c2601d04f9d
          type: string
      type: object
    handler.deprecationNotice:
      properties:
        deprecated:
          description: Whether this response concerns a deprecated field or route.
          example: true
          type: boolean
        deprecated_field:
          description: The deprecated field name.
          example: tenant_id
          type: string
        deprecated_since:
          description: API version when the field was deprecated.
          example: 2.0.1
          type: string
        message:
          description: Migration guidance message.
          example: tenant_id is deprecated; use database instead.
          type: string
        preferred_field:
          description: The canonical replacement for the deprecated field.
          example: database
          type: string
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API key
      description: 'Send your API key as Authorization: Bearer <your_api_key>.'
      scheme: bearer
      type: http

````

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