> ## 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.

# Register Webhook

> Register or update the indexing webhook for your workspace.

Registers the endpoint HydraDB calls when ingested content reaches a terminal indexing state. One webhook is registered per workspace, so calling this again replaces the current registration.

<Info>
  Omitting `signing_secret` **preserves** any secret you already have. Editing the URL or the event list never changes your signing configuration. To disable signing, call `DELETE /webhooks/indexing/signing-secret` explicitly. See [Manage the signing secret](/essentials/v2/webhooks#manage-the-signing-secret).
</Info>

Your endpoint must be reachable over public HTTPS. Localhost and private network addresses are rejected. See [Webhooks](/essentials/v2/webhooks) for the payload format, retry behaviour, and receiver examples.


## OpenAPI

````yaml api-reference/v2/openapi.json POST /webhooks/indexing
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:
    post:
      tags:
        - webhooks
      summary: Register a webhook
      description: >-
        Register the indexing webhook for this API key's org. Set
        `generate_signing_secret` to register and enable signing in one request;
        the secret is returned once on the response. Omitting `signing_secret`
        preserves any secret already configured - to disable signing, call
        DELETE /webhooks/indexing/signing-secret.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhooks.WebhookRegisterRequest'
        description: Webhook registration request
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/handler.Envelope-webhooks_WebhookRegisterResponse
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/handler.ErrorResponse'
          description: Bad Request
      security:
        - BearerAuth: []
components:
  schemas:
    webhooks.WebhookRegisterRequest:
      properties:
        event_types:
          description: Event types to subscribe to (e.g. `["indexing.status_changed"]`).
          example:
            - indexing.status_changed
          items:
            type: string
          type: array
          uniqueItems: false
        generate_signing_secret:
          description: >-
            Generate a signing secret as part of this request, so registering
            and enabling signing are one atomic operation. The secret is
            returned once on the response and cannot be retrieved later.
            Mutually exclusive with `signing_secret`.
          example: true
          type: boolean
        signing_secret:
          description: >-
            Secret used to sign webhook payloads. Deliveries carry
            `X-HydraDB-Signature: sha256=<hex>`, 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
        url:
          description: Endpoint URL to deliver webhook events to.
          example: https://docs.hydradb.com/phoenix
          type: string
      type: object
    handler.Envelope-webhooks_WebhookRegisterResponse:
      properties:
        data:
          $ref: '#/components/schemas/webhooks.WebhookRegisterResponse'
          example:
            event_types:
              - indexing.status_changed
            message: Success
            registered: true
            signing_secret: whsec_EXAMPLE_ONLY_THIS_IS_NOT_A_REAL_SIGNING_KEY
            signing_secret_configured: true
            url: https://docs.hydradb.com/phoenix
        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.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: {}
        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
            success: true
        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: true
          type: boolean
      type: object
    webhooks.WebhookRegisterResponse:
      properties:
        event_types:
          description: Event types to subscribe to (e.g. `["indexing.status_changed"]`).
          example:
            - indexing.status_changed
          items:
            type: string
          type: array
          uniqueItems: false
        message:
          description: Human-readable result message.
          example: Success
          type: string
        registered:
          description: Whether a webhook is registered for this API key.
          example: true
          type: boolean
        signing_secret:
          description: >-
            Secret used to sign webhook payloads. Deliveries carry
            `X-HydraDB-Signature: sha256=<hex>`, 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
        signing_secret_configured:
          description: >-
            Whether a signing secret has been configured for payload
            verification.
          example: true
          type: boolean
        url:
          description: Registered endpoint URL that receives webhook event deliveries.
          example: https://docs.hydradb.com/phoenix
          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:
          description: Always false for error responses.
          example: true
          type: boolean
      type: object
    handler.ErrorMeta:
      properties:
        api_version:
          type: string
        latency_ms:
          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

````