> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: Overview

> Receive indexing updates and track webhook deliveries.

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](/api-reference/v2/endpoint/source-status). One webhook is registered per organization, for the `indexing.status_changed` event. The [Webhooks guide](/essentials/v2/webhooks) covers the payload, signature verification, and receiver examples.

## Endpoints

Set up the webhook:

* [Register Webhook](/api-reference/v2/endpoint/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](/api-reference/v2/endpoint/test-webhook): `POST /webhooks/indexing/test` sends a synthetic, signed payload to confirm your endpoint and your signature check work.
* [Get Webhook](/api-reference/v2/endpoint/get-webhook): `GET /webhooks/indexing` reads the current registration and whether a signing secret is set.

Track deliveries:

* [List Deliveries](/api-reference/v2/endpoint/list-webhook-deliveries): `GET /webhooks/indexing/deliveries` lists delivery attempts, most recent first. Filter by `status` to find failures.
* [Get Delivery](/api-reference/v2/endpoint/get-webhook-delivery): `GET /webhooks/indexing/deliveries/{delivery_id}` reads one delivery, using the id from the `X-HydraDB-Delivery-ID` header.
* [Retry Delivery](/api-reference/v2/endpoint/retry-webhook-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](/api-reference/v2/endpoint/set-webhook-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](/api-reference/v2/endpoint/disable-webhook-signing): `DELETE /webhooks/indexing/signing-secret` turns signing off.
* [Delete Webhook](/api-reference/v2/endpoint/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.

## Related resources

* [Webhooks guide](/essentials/v2/webhooks): payload fields, signature verification, receiver examples, and secret rotation
* [Ingestion Status](/api-reference/v2/endpoint/source-status): polling instead of a webhook
* [Ingest Context](/api-reference/v2/endpoint/ingest-context): the ingestion that produces deliveries


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.