- 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 aPOST 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.- Click Register Webhook.
- Enter your public HTTPS endpoint.
- Select
indexing.status_changed. - Optional: enter a signing secret.
- Save the webhook.
- Use Send Test to confirm your endpoint receives a request.
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
signing_secret is optional. If you include it, your receiver should verify X-HydraDB-Signature.
Check the current registration
cURL
Edit a webhook
Use the samePOST /webhooks/indexing endpoint to replace the existing registration.
cURL
signing_secret while editing, signing is disabled for future deliveries.
Send a test delivery
cURL
Delete a webhook
cURL
3. Request format
HydraDB sends aPOST request with a JSON body.
Headers
Payload
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.test: true to ignore test events in production workflows.
5. Receiver examples
Your endpoint should return a2xx 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_idarrives again, return2xxwithout repeating side effects. - Do not depend on receiving events exactly once.
List deliveries with cURL
cURL
doc_id internally. The outbound webhook payload uses id.
Filter deliveries
cURL
pendingsweepingdeliveredfailedpermanently_failed
Paginate deliveries
Whennext_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
Onlyfailed and permanently_failed deliveries can be retried manually.
cURL
7. Security checklist
- Use HTTPS for your webhook URL.
- Configure a signing secret in the dashboard.
- Verify
X-HydraDB-Signatureusing the raw request body. - Return
2xxonly after you accept the event. - Deduplicate using
delivery_id. - Keep the endpoint fast. Put slow work in a queue or background job.