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 organization, 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.
Manage signing or remove the webhook:
  • Set Signing Secret: POST /webhooks/indexing/signing-secret generates a new signing secret, or stores one you supply. The secret is returned once and takes effect immediately. If you supply the new secret, configure your receiver to accept it before this call.
  • Disable Signing: DELETE /webhooks/indexing/signing-secret turns signing off.
  • 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 contains the event body and an X-HydraDB-Delivery-ID header. Signed deliveries also include X-HydraDB-Signature.
  • Failed deliveries retry with exponential backoff. HydraDB Cloud marks a delivery permanently_failed after 16 attempts or 48 hours after the first failure, whichever comes first.
  • Automatic and manual retries use your current signing 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.