Hooks | Alephant Documentation

Hooks receive events from external systems and trigger approved automations or agent flows. Use them for event-driven integration, not as unauthenticated general execution endpoints. This entry is typically visible only when enterprise hooks are enabled for the deployment.

Management Boundary

Area	Guidance
Entry	Create separate hooks for separate systems instead of sharing one broad endpoint.
Authentication	Validate signatures, tokens, or source restrictions.
Scope	Trigger only explicitly configured workflows or operations.
Audit	Record event ID, source, matched rule, result, and failure reason.

Concepts

Concept	Meaning	Governance decision
Hook point	A defined stage in the AIvis pipeline where custom logic can be called.	Treat each point as a stable contract: understand when it runs, which data it receives, and whether it can modify or block the pipeline.
Hook	The connection between one hook point and your HTTPS endpoint.	Use one purpose-built endpoint per hook point and environment. Avoid broad multiplexing that hides ownership and failure impact.
Endpoint	Your service that receives the JSON request and returns the expected response.	Keep it reachable only from approved networks, validate authentication, and return quickly.
Fail strategy	The behavior AIvis follows when the endpoint is unreachable, slow, or returns an invalid response.	Use hard fail when continuing would violate policy. Use soft fail when the hook is informational and the core pipeline can safely continue.

Common Hook Points

Hook point	When it runs	What it can do	Default stance
Document ingestion	After document validation and before indexing starts.	Pass content through, rewrite sections, or reject a document before it enters the index.	Prefer hard fail for policy enforcement, classification, redaction, and source allowlists.
Document push	After a document is successfully indexed.	Notify or copy indexed content to an external system such as an audit log, warehouse, or downstream archive.	Prefer soft fail unless the downstream destination is part of a mandatory compliance process.
Query processing	Immediately after a user submits a query and before downstream retrieval or model calls.	Pass the query through, rewrite it, or reject it with a user-facing message.	Prefer hard fail for access policy, data-loss prevention, or regulated-topic controls.

The exact payload and response schema belongs to the hook point contract. Do not assume two hook points accept the same fields just because both use HTTP POST.

Before Configuration

Define the event source, event types, and allowed actions.
Add signature validation and replay protection for each hook.
Plan retry, idempotency, and alerting behavior.
Decide which hook point is allowed to affect the pipeline and which should only observe or notify.
Choose the fail strategy and timeout before connecting the endpoint.
Prepare an endpoint that returns valid JSON and a 2xx status for accepted requests.
Store any endpoint API key in a managed secret store and rotate it with the owning service.

Connect a Hook

Open the AIvis admin area and go to the hooks page.
Select the hook point you want to connect.
Provide a display name that includes the system, environment, and purpose.
Enter the HTTPS endpoint URL. Do not use a public test endpoint for production data.
Configure authentication, timeout, and fail strategy.
Save the hook only after the endpoint passes the connection test.

Field	Required	Guidance
Display name	Yes	Use a name such as `pii-redaction-prod` or `audit-export-staging` so logs remain readable.
Endpoint URL	Yes	Use HTTPS and route to a service owned by the team responsible for the hook behavior.
API key	Optional	When configured, validate the incoming `Authorization: Bearer <key>` header before processing the payload.
Timeout	Optional	Keep the value short enough to protect user-facing latency and worker throughput.
Fail strategy	Optional	Select hard fail for blocking controls and soft fail for telemetry or best-effort notifications.

Managing Hooks

Operation	Use it when	Check after the change
Activate or deactivate	You need to start or pause execution without deleting the configuration.	Confirm the expected pipeline behavior with a controlled event.
Edit	The endpoint URL, API key, timeout, name, or fail strategy changes.	Re-run positive, negative, timeout, and invalid-response tests.
View logs	A hook is degraded, failing, or producing unexpected decisions.	Compare event IDs and failure reasons with the owning service logs.
Delete	The integration is retired or replaced.	Remove the endpoint secret and update the owning team’s runbook.

Health and Failure Handling

Monitor hook health after registration. A healthy endpoint is reachable and has no recent execution failures. A degraded endpoint may still be reachable but should be treated as an active reliability or policy risk. A lost connection means AIvis cannot reach the endpoint and will follow the configured fail strategy.

For hard-fail hooks, test the user or indexing experience that appears when the hook rejects, times out, or returns invalid JSON. For soft-fail hooks, confirm the main pipeline continues while the failure is still visible in logs and alerts.

Verification

Validate the path with a legitimate event.
Test missing signatures, wrong signatures, and repeated events.
Confirm query history can trace event handling results.
Test timeout behavior and invalid JSON responses.
Confirm hard-fail hooks block the intended action and soft-fail hooks continue safely.
Confirm the endpoint does not log raw secrets, full credentials, or unnecessary user content.
Confirm request IDs, event IDs, and rejection reasons can be joined across AIvis logs and the endpoint logs.

Production Checklist

Each hook has one owner, one environment, and one explicit hook point.
Endpoint access is restricted by HTTPS, authentication, and network controls.
The endpoint is idempotent for retries and duplicate events.
Blocking hooks have user-facing or operator-facing failure messages that explain the next step without leaking policy internals.
Hook decisions are auditable, including pass-through, rewrite, rejection, timeout, and endpoint failure outcomes.