Skip to main content
A webhook is an HTTP POST that HydraDB sends to your endpoint when ingested content reaches a terminal indexing state, completed or errored, so you do not have to poll Ingestion Status. One webhook is registered per workspace, for the indexing.status_changed event. The Webhooks guide covers the payload, signature verification, and receiver examples.

​
Endpoints

Set up the webhook:
  • Register Webhook: POST /webhooks/indexing registers your endpoint, or replaces the current registration. Send generate_signing_secret: true to get a signing secret in the same call.
  • Send Test Delivery: POST /webhooks/indexing/test sends a synthetic, signed payload to confirm your endpoint and your signature check work.
  • Get Webhook: GET /webhooks/indexing reads the current registration and whether a signing secret is set.
Track deliveries:
  • List Deliveries: GET /webhooks/indexing/deliveries lists delivery attempts, most recent first. Filter by status to find failures.
  • Get Delivery: GET /webhooks/indexing/deliveries/{delivery_id} reads one delivery, using the id from the X-HydraDB-Delivery-ID header.
  • Retry Delivery: POST /webhooks/indexing/deliveries/{delivery_id}/retry queues a failed or permanently_failed delivery for another attempt.
Change or remove it:
  • POST /webhooks/indexing/signing-secret generates a new signing secret, or stores one you supply. The secret is returned once and takes effect immediately, so rotate only once your receiver accepts the new one.
  • DELETE /webhooks/indexing/signing-secret turns signing off. It is the only way to; editing the registration never clears the secret.
  • Delete Webhook: DELETE /webhooks/indexing removes the registration and its signing secret.

​
Typical call sequence

  1. POST /webhooks/indexing with your HTTPS endpoint and generate_signing_secret: true. Store the secret it returns.
  2. POST /webhooks/indexing/test to check your receiver accepts the delivery and verifies the signature.
  3. Ingest content as usual. Each item that finishes indexing produces one delivery.
  4. GET /webhooks/indexing/deliveries?status=failed to find deliveries your endpoint rejected, then retry them once the problem is fixed.

​
Delivery and retries

Each delivery carries the event in its body and an X-HydraDB-Delivery-ID header; with signing on, it also carries an X-HydraDB-Signature header. A failed delivery is retried with exponential backoff until it succeeds. On HydraDB Cloud it is marked permanently_failed after 16 attempts, or 48 hours after the first failure, whichever comes first. A retry, automatic or manual, is signed with your current secret. Test deliveries do not appear in the delivery history. Your endpoint must be reachable over public HTTPS; localhost and private network addresses are rejected.