> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Hooks > Manage webhook-style event entry points into AIvis with signature, scope, and replay controls. 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 1. Open the AIvis admin area and go to the hooks page. 2. Select the hook point you want to connect. 3. Provide a display name that includes the system, environment, and purpose. 4. Enter the HTTPS endpoint URL. Do not use a public test endpoint for production data. 5. Configure authentication, timeout, and fail strategy. 6. 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 ` 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.