Skip to main content
POST
Register a webhook
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.
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.
Your endpoint must be reachable over public HTTPS. Localhost and private network addresses are rejected. See Webhooks for the payload format, retry behaviour, and receiver examples.

Authorizations

Authorization
string
header
required

API key sent as a Bearer token: "Bearer prefix.secret"

Body

application/json

Webhook registration request

event_types
string[]

Event types to subscribe to (e.g. ["indexing.status_changed"]).

Example:
generate_signing_secret
boolean

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

signing_secret
string

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"

url
string

Endpoint URL to deliver webhook events to.

Example:

"https://docs.hydradb.com/phoenix"

Response

Created

data
object
Example:
error
object

Error message, empty string on success.

Example:
meta
object
Example:
success
boolean

Whether the request succeeded.

Example:

true