Skip to main content
Webhooks let your application receive an HTTP callback when HydraDB finishes processing a document or memory. Use them when you want to:
  • Update your own database when content is ready for query
  • Notify users that an upload has finished
  • Trigger downstream jobs after indexing completes
  • Track indexing failures without polling
Webhooks are sent for terminal indexing states. For progress updates before completion, use Ingestion Status.

1. How it works

When an ingested item reaches a terminal state, HydraDB creates a delivery record and sends a POST request to your webhook URL. The supported event today is: success is a legacy alias for completed.

2. Register a webhook

Open the HydraDB dashboard and go to Webhooks.
  1. Click Register Webhook.
  2. Enter your public HTTPS endpoint.
  3. Select indexing.status_changed.
  4. Optional: enter a signing secret.
  5. Save the webhook.
  6. Use Send Test to confirm your endpoint receives a request.
Your webhook URL must be reachable from the public internet. Localhost and private network addresses are blocked.
Webhook management endpoints return their response object directly, not inside the standard v2 { success, data, error, meta } envelope used by /databases, /context/*, and /query.

Register with cURL

Use your HydraDB API key to register a webhook from your backend or terminal.
cURL
Response:
signing_secret is optional. If you include it, your receiver should verify X-HydraDB-Signature.

Check the current registration

cURL
Response:

Edit a webhook

Use the same POST /webhooks/indexing endpoint to replace the existing registration.
cURL
If you omit signing_secret while editing, signing is disabled for future deliveries.

Send a test delivery

cURL
Response:

Delete a webhook

cURL
Response:

3. Request format

HydraDB sends a POST request with a JSON body.

Headers

Payload

For failed indexing, the payload can include error_code and error_message:
Older examples may refer to this document identifier as doc_id. New webhook payloads use id.

4. Test delivery payload

The dashboard Send Test button sends a synthetic event. It does not create a real indexing delivery.
Use test: true to ignore test events in production workflows.

5. Receiver examples

Your endpoint should return a 2xx response quickly. Do any slow work after you acknowledge the request.

6. Delivery and retries

HydraDB records every delivery attempt. You can inspect delivery history from the dashboard Webhooks page. Delivery states: HydraDB retries failed deliveries in the background. If a worker shuts down during delivery, the sweep process recovers the event later. Your receiver should be idempotent:
  • Store delivery_id.
  • If the same delivery_id arrives again, return 2xx without repeating side effects.
  • Do not depend on receiving events exactly once.

List deliveries with cURL

cURL
Response:
Delivery history uses doc_id internally. The outbound webhook payload uses id.

Filter deliveries

cURL
Valid filters are:
  • pending
  • sweeping
  • delivered
  • failed
  • permanently_failed

Paginate deliveries

When next_cursor is not null, pass it back as cursor.
cURL
limit can be between 1 and 100.

Get one delivery

Replace <delivery_id> with a value from a webhook payload or from the delivery list response.
cURL

Retry a failed delivery

Only failed and permanently_failed deliveries can be retried manually.
cURL
Response:

7. Security checklist

  • Use HTTPS for your webhook URL.
  • Configure a signing secret in the dashboard.
  • Verify X-HydraDB-Signature using the raw request body.
  • Return 2xx only after you accept the event.
  • Deduplicate using delivery_id.
  • Keep the endpoint fast. Put slow work in a queue or background job.

8. Common issues