> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-docs-pro-2457-api-response-cleanup.mintlify.site/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: >-
HydraDB Application API — knowledge ingestion, search, and memory
management.
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: >-
Generates a signing secret, or stores one you supply. The plaintext is
returned exactly once and cannot be retrieved afterwards. Takes effect
immediately, so rotate only once your receiver accepts the new secret.
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 used to sign webhook payloads. Deliveries carry
`X-HydraDB-Signature: sha256=`, the HMAC-SHA256 of the raw
request body keyed by this secret. Minimum 16 characters when you
supply your own; omit it and one is generated for you. On
registration, omitting this field preserves any existing secret - to
disable signing, call DELETE /webhooks/indexing/signing-secret.
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'
- type: 'null'
description: Null on success; an object with code and message on failure.
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: team_docs
tenant_id: acme_corp
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: >-
Secret used to sign webhook payloads. Deliveries carry
`X-HydraDB-Signature: sha256=`, the HMAC-SHA256 of the raw
request body keyed by this secret. Minimum 16 characters when you
supply your own; omit it and one is generated for you. On
registration, omitting this field preserves any existing secret - to
disable signing, call DELETE /webhooks/indexing/signing-secret.
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
message:
description: Human-readable description of the error.
example: Database not found
type: string
type: object
handler.responseMeta:
properties:
api_version:
description: >-
APIVersion echoes the version of the API that served the request
(PRO-1209),
sourced from reqmeta.APIVersion — the same value carried by OpenAPI
info.version and /health — so a client always knows which API
version
produced a response. Always present (no omitempty).
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: >-
Deprecation lists any migration nudges that apply to this request —
the
caller used a legacy /tenants route, a legacy
tenant_id/sub_tenant_id field,
or the deprecated sub_tenant_ids selector. It is a non-breaking
signal (the
status code is unchanged); omitempty keeps it absent for
fully-migrated
requests. A list so independent deprecations coexist without
clobbering.
items:
$ref: '#/components/schemas/handler.deprecationNotice'
type: array
uniqueItems: false
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
source_type:
description: Type of the parent source (e.g. `file`, `slack`, `notion`).
example: file
type: string
sub_tenant_id:
deprecated: true
example: sub_tenant_4567
type: string
x-deprecated: 'true'
tenant_id:
deprecated: true
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: 'API key sent as a Bearer token: "Bearer prefix.secret"'
scheme: bearer
type: http
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.