> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-docs-pro-2457-api-response-cleanup.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks: Overview

> Every webhook endpoint, the order to call them in, and how deliveries are signed and retried.

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 workspace, 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.

Change or remove it:

* `POST /webhooks/indexing/signing-secret` generates a new signing secret, or stores one you supply. The secret is returned once and takes effect immediately, so rotate only once your receiver accepts the new one.
* `DELETE /webhooks/indexing/signing-secret` turns signing off. It is the only way to; editing the registration never clears the secret.
* [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 carries the event in its body and an `X-HydraDB-Delivery-ID` header; with signing on, it also carries an `X-HydraDB-Signature` header. A failed delivery is retried with exponential backoff until it succeeds. On HydraDB Cloud it is marked `permanently_failed` after 16 attempts, or 48 hours after the first failure, whichever comes first. A retry, automatic or manual, is signed with your current 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.