Webhooks

A webhook is an HTTP POST that HydraDB sends to your endpoint when an ingested document, memory, or app source finishes indexing: completed or errored. Use it to mark a document as ready in your own database, tell a user their upload finished, kick off a downstream job, or catch indexing failures without polling. You register one endpoint per organization with POST /webhooks/indexing. For progress before then, poll GET /context/status. In this guide:

Register a webhook with signing turned on.
Read the payload you receive: headers and fields.
Verify the signature: with the SDK helper, or in a few lines of your own, plus full receiver examples.
Track deliveries and retries: states, idempotency, and the delivery history.
Manage the signing secret: generate, supply, disable, and rotate without a gap.
Security checklist, common issues, and related pages.

1. Register a webhook

This request registers your endpoint for the one supported event, indexing.status_changed, and asks HydraDB to generate a signing secret in the same call. The secret is returned once and cannot be read again; copy it into your receiver’s secret store right away.

import os
from hydra_db import HydraDB

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])

result = client.webhooks.register(
    url="https://api.example.com/webhooks/hydradb",
    event_types=["indexing.status_changed"],
    generate_signing_secret=True,
)
# The signing secret is in result.data. It is shown once.

import { HydraDBClient } from "@hydradb/sdk";

const client = new HydraDBClient({
  token: process.env.HYDRA_DB_API_KEY,
});

const result = await client.webhooks.register({
  url: "https://api.example.com/webhooks/hydradb",
  eventTypes: ["indexing.status_changed"],
  generateSigningSecret: true,
});
// The signing secret is in result.data. It is shown once.

curl -X POST 'https://api.hydradb.com/webhooks/indexing' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/hydradb",
    "event_types": ["indexing.status_changed"],
    "generate_signing_secret": true
  }'

{
  "registered": true,
  "url": "https://api.example.com/webhooks/hydradb",
  "event_types": ["indexing.status_changed"],
  "signing_secret_configured": true,
  "signing_secret": "whsec_Yk8sQ2pWc0xuNGRIeUZ0UmJKZ1B3WHZNaTdaYUUxcW8",
  "message": "Webhook registered and signing enabled. Copy the signing secret now - it cannot be retrieved later."
}

What each property means

Property	What it is
`url`	Your endpoint. It must be reachable over public HTTPS; localhost and private network addresses are rejected.
`event_types`	The events to subscribe to. `indexing.status_changed` is the only one today. It fires when an item reaches `completed`, `errored`, or `success`; `success` is a legacy alias for `completed`.
`generate_signing_secret`	Ask HydraDB to create a strong secret and return it once. Send this or `signing_secret`, not both; sending both returns `422`.
`signing_secret`	Supply your own secret instead, at least 16 characters. Useful when you want to deploy it to your receiver before HydraDB starts using it.

Signing is optional but strongly recommended: without it, your endpoint cannot tell a real HydraDB delivery from anything else that can reach the URL. Section 3 shows how to verify it. Calling POST /webhooks/indexing again replaces the registration. Omitting signing_secret then preserves the secret you already have; changing the URL or the event list never changes signing. To turn signing off, call DELETE /webhooks/indexing/signing-secret, as in section 5. The Webhooks page of the dashboard registers too: enter the URL, enable signing, and copy the secret when it is shown. Either way, send a test delivery next to confirm the endpoint is reachable and your verifier works.

Check, replace, test, or delete the registration: cURL

curl 'https://api.hydradb.com/webhooks/indexing' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

{
  "registered": true,
  "url": "https://api.example.com/webhooks/hydradb",
  "event_types": ["indexing.status_changed"],
  "signing_secret_configured": true
}

curl -X POST 'https://api.hydradb.com/webhooks/indexing' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/hydradb-v2",
    "event_types": ["indexing.status_changed"]
  }'

curl -X POST 'https://api.hydradb.com/webhooks/indexing/test' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

{
  "delivered": true,
  "status_code": 204,
  "message": "Test delivery succeeded."
}

curl -X DELETE 'https://api.hydradb.com/webhooks/indexing' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

signing_secret_configured only says whether a secret is set; the secret itself is never returned. Deleting the webhook discards the stored secret along with the registration.

The management endpoints return the standard v2 { success, data, error, meta } envelope used by /databases, /context/*, and /query; the examples on this page show only data. The event sent to your webhook URL is not wrapped.

2. Read the payload you receive

Each delivery is a POST with a JSON body and these headers:

Header	Description
`Content-Type`	Always `application/json`
`X-HydraDB-Delivery-ID`	Stable delivery ID for this event
`X-HydraDB-Event`	Event name, such as `indexing.status_changed`
`X-HydraDB-Signature`	`sha256=<hex>`, the HMAC-SHA256 of the raw request body keyed by your signing secret. Present only when signing is configured. See Verify the signature

Delivery payloads for completed, errored, and test events: JSON

{
  "event": "indexing.status_changed",
  "delivery_id": "<delivery_id>",
  "id": "<id>",
  "tenant_id": "<database_id>",
  "database": "<database>",
  "sub_tenant_id": "<collection>",
  "collection": "<collection>",
  "status": "completed",
  "timestamp": "<ISO-8601 timestamp>"
}

{
  "event": "indexing.status_changed",
  "delivery_id": "<delivery_id>",
  "id": "<id>",
  "tenant_id": "<database_id>",
  "database": "<database>",
  "sub_tenant_id": "<collection>",
  "collection": "<collection>",
  "status": "errored",
  "timestamp": "<ISO-8601 timestamp>",
  "error_code": "<error_code>",
  "error_message": "<error_message>"
}

{
  "event": "indexing.status_changed",
  "delivery_id": "test_<random>",
  "id": "test_document",
  "tenant_id": "<org_id>",
  "database": "<org_id>",
  "sub_tenant_id": "<org_id>",
  "collection": "<org_id>",
  "status": "completed",
  "timestamp": "<ISO-8601 timestamp>",
  "test": true
}

A test delivery is synthetic: nothing was ingested, so there is no database name to report, and every scope field, including database, is set to your organization ID. Match on test: true (or the test_ prefix on delivery_id) to tell it apart from a real delivery.

Field	Description
`event`	Event type. Currently `indexing.status_changed`.
`delivery_id`	Stable ID for this event. Store it to deduplicate retries.
`id`	The document, memory, or app source ID you supplied during ingestion.
`database`	The name of the database you ingested into: the value you sent as `database` (or `tenant_id`) on the ingest request. Empty only for items ingested before this field existed; read `tenant_id` if you need a scope that is always set.
`collection`	Collection scope for the indexed item.
`status`	Terminal indexing status. Usually `completed` or `errored`.
`timestamp`	Time the webhook payload was created.
`error_code`	Present when available for failed processing.
`error_message`	Present when available for failed processing.
`tenant_id`	Deprecated. An identifier for the database, not the name you ingested into. Always present.
`sub_tenant_id`	Deprecated alias for `collection`, carrying the same value.

Route and filter on database, not tenant_id; database is the name you sent. New integrations should read database and collection.

3. Verify the signature

When signing is configured, every delivery carries X-HydraDB-Signature: sha256=<lowercase hex digest>, where the digest is HMAC-SHA256 with your signing secret as the key over the raw request body bytes. Three details decide whether your verifier works:

The sha256= prefix is part of the header value, not a separate field. Compare against the whole string.
The digest is lowercase hex, not base64.
The HMAC is computed over the raw body bytes exactly as received. Parsing the JSON and re-serializing it produces different bytes, so the signature will not match.

The official SDKs include a verifier:

Verify with the SDK helper: Python or TypeScript

from hydra_db.helpers import verify_webhook_signature

if not verify_webhook_signature(secret, raw_body, signature):
    ...  # reject

import { verifyWebhookSignature } from "@hydradb/sdk/helpers";

if (!verifyWebhookSignature(secret, rawBody, signature)) {
  // reject
}

Otherwise, implement it directly. Both versions use a constant-time comparison, which matters: a naive == leaks timing information that can be used to forge a signature byte by byte.

Verify without the SDK: Python or TypeScript

import hashlib
import hmac


def verify_webhook_signature(secret: str, raw_body: bytes, signature: str) -> bool:
    """Return True when signature is valid for raw_body."""
    if not secret or not signature:
        return False
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, f"sha256={digest}")

import crypto from "node:crypto";

export function verifyWebhookSignature(
  secret: string,
  rawBody: Buffer,
  signature: string | undefined,
): boolean {
  if (!secret || !signature) {
    return false;
  }
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const expectedBuffer = Buffer.from(expected);
  const signatureBuffer = Buffer.from(signature);

  // timingSafeEqual throws on a length mismatch, so guard before comparing.
  if (signatureBuffer.length !== expectedBuffer.length) {
    return false;
  }
  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}

If the signing secret is missing from your environment, reject the request rather than skipping verification. Return a 2xx quickly and do slow work after acknowledging the request. These receivers wire the verifier into a handler; both read the raw body before parsing.

Receiver examples: Python (FastAPI) or TypeScript (Express)

import hashlib
import hmac
import json
import os

from fastapi import FastAPI, Header, Request, Response

app = FastAPI()

# Fail fast at startup when the secret is missing, rather than accepting
# unverified deliveries at request time.
SIGNING_SECRET = os.environ["HYDRADB_WEBHOOK_SECRET"]


def verify_webhook_signature(secret: str, raw_body: bytes, signature: str | None) -> bool:
    if not secret or not signature:
        return False
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, f"sha256={digest}")


@app.post("/webhooks/hydradb")
async def hydradb_webhook(
    request: Request,
    delivery_id: str | None = Header(default=None, alias="X-HydraDB-Delivery-ID"),
    signature: str | None = Header(default=None, alias="X-HydraDB-Signature"),
):
    raw_body = await request.body()

    if not verify_webhook_signature(SIGNING_SECRET, raw_body, signature):
        return Response(status_code=401)

    event = json.loads(raw_body)

    # Store delivery_id and skip it if you have already processed it.
    print("HydraDB webhook", delivery_id, event["id"], event["status"])

    return Response(status_code=204)

import crypto from "node:crypto";
import express from "express";

const app = express();

// Fail fast at startup when the secret is missing, rather than accepting
// unverified deliveries at request time.
const signingSecret = process.env.HYDRADB_WEBHOOK_SECRET;
if (!signingSecret) {
  throw new Error("HYDRADB_WEBHOOK_SECRET is required");
}

function verifyWebhookSignature(
  secret: string,
  rawBody: Buffer,
  signature: string | undefined,
): boolean {
  if (!secret || !signature) {
    return false;
  }
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");

  const expectedBuffer = Buffer.from(expected);
  const signatureBuffer = Buffer.from(signature);

  if (signatureBuffer.length !== expectedBuffer.length) {
    return false;
  }
  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}

app.post(
  "/webhooks/hydradb",
  // express.raw is essential: the signature covers the raw bytes, so the body
  // must not be parsed before verification.
  express.raw({ type: "application/json" }),
  (req, res) => {
    const deliveryId = req.header("X-HydraDB-Delivery-ID");
    const signature = req.header("X-HydraDB-Signature");
    const rawBody = req.body as Buffer;

    if (!verifyWebhookSignature(signingSecret, rawBody, signature)) {
      return res.status(401).send("Invalid signature");
    }

    const event = JSON.parse(rawBody.toString("utf8"));

    // Store deliveryId and skip it if you have already processed it.
    console.log("HydraDB webhook", deliveryId, event.id, event.status);

    return res.status(204).send();
  }
);

app.listen(3000);

4. Track deliveries and retries

When an item reaches a terminal state, HydraDB creates a delivery record, sends the POST, and marks the record delivered or schedules a retry. Every attempt is recorded, and the history is on the dashboard Webhooks page and over the API.

State	Meaning
`pending`	The event was recorded and is waiting to be sent.
`sweeping`	HydraDB has claimed the event for delivery or retry.
`delivered`	Your endpoint returned a successful status code.
`failed`	The current send attempt failed and will be retried.
`permanently_failed`	HydraDB stopped retrying this event. On HydraDB Cloud this happens after 16 attempts, or 48 hours after the first failure, whichever comes first.

If a worker shuts down during delivery, the sweep process recovers the event later. Test deliveries do not appear in the history. Because of retries, your receiver should be idempotent:

Store delivery_id.
If the same delivery_id arrives again, return 2xx without repeating side effects.

List, filter, page, fetch, and retry deliveries: cURL

curl 'https://api.hydradb.com/webhooks/indexing/deliveries?limit=20' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

{
  "deliveries": [
    {
      "delivery_id": "<delivery_id>",
      "doc_id": "<id>",
      "status": "delivered",
      "indexing_status": "completed",
      "event_type": "indexing.status_changed",
      "attempts": 1,
      "error_code": null,
      "error_message": null,
      "created_at": "<ISO-8601 timestamp>",
      "updated_at": "<ISO-8601 timestamp>"
    }
  ],
  "count": 1,
  "next_cursor": null
}

curl 'https://api.hydradb.com/webhooks/indexing/deliveries?limit=20&status=failed' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

curl 'https://api.hydradb.com/webhooks/indexing/deliveries?limit=20&cursor=<next_cursor>' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

curl 'https://api.hydradb.com/webhooks/indexing/deliveries/<delivery_id>' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

curl -X POST 'https://api.hydradb.com/webhooks/indexing/deliveries/<delivery_id>/retry' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

{
  "delivery_id": "<delivery_id>",
  "queued": true,
  "message": "Delivery queued for retry."
}

The history uses doc_id for the item; the outbound payload uses id. status accepts any of the delivery states above. limit is 1 to 100 (default 20); when next_cursor is not null, pass it back as cursor. <delivery_id> is the value from a payload or from the list.

Only failed and permanently_failed deliveries can be retried by hand; for any other state the call returns queued: false. A retry is signed with your current signing secret, not the one in force when the delivery was first attempted, so after a rotation your receiver must know the new secret.

5. Manage the signing secret

POST /webhooks/indexing/signing-secret enables or rotates signing after registration, and DELETE on the same path disables it. Two ways to set a secret:

Let HydraDB generate one: send no body. The secret is returned exactly once, in plain text, and takes effect immediately.
Supply your own: send signing_secret, at least 16 characters. Use this when you want to deploy the secret to your receiver first and hand it to HydraDB afterwards, so there is no window where deliveries are signed with a secret your endpoint does not yet know.

Generate, supply, or disable the signing secret: cURL

curl -X POST 'https://api.hydradb.com/webhooks/indexing/signing-secret' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

{
  "signing_secret": "whsec_Yk8sQ2pWc0xuNGRIeUZ0UmJKZ1B3WHZNaTdaYUUxcW8",
  "generated": true,
  "message": "Signing secret generated. Copy it now - it cannot be retrieved later, and it takes effect immediately."
}

curl -X POST 'https://api.hydradb.com/webhooks/indexing/signing-secret' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{ "signing_secret": "at-least-16-characters" }'

curl -X DELETE 'https://api.hydradb.com/webhooks/indexing/signing-secret' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2"

Disabling removes the stored secret, and deliveries stop carrying X-HydraDB-Signature.

Rotating takes effect immediately, with no overlap period. Deliveries in flight during a rotation are signed with the new secret, so a receiver that only knows the old one will reject them. Rotate without downtime shows how to avoid the gap.

Rotate without downtime

HydraDB signs each delivery with one secret, so the overlap has to live in your receiver: deploy it with both secrets before rotating in HydraDB, and supply the new secret yourself so you know it before it takes effect.

Choose the new secret yourself

Generate a high-entropy value with your own tooling, for example openssl rand -base64 32. Do not use the generate option here: a generated secret is only revealed after it is already in effect, which is the window you are trying to avoid.

Teach your receiver both secrets

Deploy your receiver so it accepts either the current secret or the new one, reading both from your environment. At this point nothing has changed on the HydraDB side, so every delivery still verifies against the old secret.

Rotate in HydraDB, supplying that secret

In the dashboard, open Rotate, tick I’ll use my own secret, and paste the value. Over the API, call POST /webhooks/indexing/signing-secret with a signing_secret body. Deliveries switch to the new secret immediately, and your receiver already accepts it.

Retire the old secret

Once you have confirmed deliveries are verifying against the new secret, remove the old one from your receiver and redeploy. You are back to a single active secret.

A receiver that accepts either secret: Python or TypeScript

import hashlib
import hmac
import os

# During a rotation both are set. Afterwards, drop HYDRADB_WEBHOOK_SECRET_OLD.
SECRETS = [
    s for s in (
        os.environ["HYDRADB_WEBHOOK_SECRET"],
        os.environ.get("HYDRADB_WEBHOOK_SECRET_OLD"),
    ) if s
]


def verify_webhook_signature(raw_body: bytes, signature: str) -> bool:
    if not signature:
        return False
    for secret in SECRETS:
        digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
        if hmac.compare_digest(signature, f"sha256={digest}"):
            return True
    return False

import crypto from "node:crypto";

// During a rotation both are set. Afterwards, drop HYDRADB_WEBHOOK_SECRET_OLD.
const secrets = [
  process.env.HYDRADB_WEBHOOK_SECRET,
  process.env.HYDRADB_WEBHOOK_SECRET_OLD,
].filter((s): s is string => Boolean(s));

export function verifyWebhookSignature(rawBody: Buffer, signature: string | undefined): boolean {
  if (!signature) {
    return false;
  }
  return secrets.some((secret) => {
    const expected =
      "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
    const expectedBuffer = Buffer.from(expected);
    const signatureBuffer = Buffer.from(signature);
    if (signatureBuffer.length !== expectedBuffer.length) {
      return false;
    }
    return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
  });
}

Security checklist

Use HTTPS for your webhook URL.
Enable signing with a cryptographically random secret, generated by HydraDB or your own tooling.
Verify X-HydraDB-Signature using the raw request body, with a constant-time comparison.
Fail closed. Reject the request when the secret is missing from your environment, rather than skipping verification.
Store the secret as a secret. It belongs in your secret manager, not in source control.
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.

Common issues

Issue	What to check
Test delivery fails	Confirm your endpoint is public and returns a `2xx` status.
Signature check fails	Verify the HMAC is computed over the raw request body, not parsed JSON. Check you are comparing against the whole header value including the `sha256=` prefix, and that the digest is lowercase hex rather than base64.
Signature header is missing	Signing is not configured. Call `POST /webhooks/indexing/signing-secret` to enable it.
Signatures started failing after a rotation	Rotation applies immediately. Confirm your receiver has the new secret deployed, and see Rotate without downtime to avoid the gap next time.
Event arrives more than once	This is expected during retries. Deduplicate with `delivery_id`.
Event never arrives	Check the delivery history for `failed` or `permanently_failed`. Test deliveries are not listed there.
`id` is unexpected	It is the ID you supplied at ingestion, such as a document ID, a memory ID, or an app source ID.

Register Webhook: the full request and response reference, with the other webhook endpoints alongside it
Ingestion Status: poll for progress before an item reaches a terminal state
Knowledge: ingesting the documents whose indexing these events report on
SDKs: client setup for the Python and TypeScript examples

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Register a webhook

What each property means

2. Read the payload you receive

3. Verify the signature

4. Track deliveries and retries

5. Manage the signing secret

Rotate without downtime

Security checklist

Common issues

​1. Register a webhook

​What each property means

​2. Read the payload you receive

​3. Verify the signature

​4. Track deliveries and retries

​5. Manage the signing secret

​Rotate without downtime

​Security checklist

​Common issues

​Related

1. Register a webhook

What each property means

2. Read the payload you receive

3. Verify the signature

4. Track deliveries and retries

5. Manage the signing secret

Rotate without downtime

Security checklist

Common issues

Related