Hook Extensions

Hook Extensions are an Enterprise Edition feature and are only available on single-tenant deployments.

Overview#

Hook Extensions let you inject custom logic into Nexus's pipeline at defined stages. without modifying Nexus source code. You provide an HTTP endpoint; Nexus calls it at the right moment, sends a JSON payload, and uses your response to influence what happens next.

Concepts#

Hook Points#

A hook point is a defined stage in Nexus's pipeline where custom logic can be injected. Each hook point specifies:

• When it fires in the pipeline

• What payload it sends to your endpoint

• What response it expects back

• A default timeout and fail strategy

Hook points are intentional. once a hook point is added, Nexus commits to maintaining its payload structure, response format, and behavior. meaning it won't change in a breaking way without a proper deprecation process. Because of this long-term commitment, each proposal is evaluated carefully before being added.

Hooks#

A hook connects a hook point to your HTTPS endpoint. When the hook point is triggered, Nexus POSTs a request to your endpoint and uses your response to continue, modify, or abort the pipeline.

Only one hook per hook point is allowed at a time.

How It Works#

Nexus reaches a hook point in the pipeline#

The pipeline triggers at a defined stage.

Nexus POSTs to your endpoint#

If an active hook is configured for that point, Nexus sends a JSON payload to your endpoint URL.

Your endpoint responds#

Your endpoint processes the payload and returns a JSON response.

Nexus continues#

Nexus uses your response to continue, modify, or abort the pipeline.

If your endpoint is unreachable, times out, or returns an invalid response, Nexus follows the fail strategy you configured.

Adding a Hook#

Navigate to Hook Extensions#

Go to the Admin Panel and select Hook Extensions.

Connect a hook point#

Find the hook point you want to use and click Connect.

Fill in the hook details#

Complete the form:

Connect#

Click Connect. Nexus validates your endpoint with a test request before saving. On success, the hook appears in the connected list.

Managing a Hook#

Once connected, you can:

• Activate / Deactivate. toggle whether the hook runs

• Edit. update the name, endpoint URL, API key, timeout, or fail strategy

• Delete. remove the hook entirely

• View Logs. inspect recent execution failures for debugging

Hook Health#

Nexus monitors your endpoint after the hook is registered and connected, displays its current health status.

The 10 most recent failures from the past 30 days are also shown to help with debugging.

Document Ingestion#

The Document Ingestion hook point lets you intercept every document before it enters the Nexus indexing pipeline. Your endpoint receives the fully-formed document and can filter it out, rewrite its content, or pass it through unchanged.

It runs immediately after Nexus's internal validation and before the indexing pipeline begins. no partial writes have occurred yet.

Input Schema#

Nexus sends a POST request to your endpoint once per document with the following JSON body:

{
"document_id": "string",
"title": "string | null",
"semantic_identifier": "string",
"source": "string",
"sections": [
  {
    "text": "string | null",
    "link": "string | null",
    "image_file_id": "string | null"
  }
],
"metadata": { "key": ["string"] },
"doc_updated_at": "string | null",
"primary_owners": [
  { "display_name": "string | null", "email": "string | null" }
],
"secondary_owners": [
  { "display_name": "string | null", "email": "string | null" }
]
}

All input fields are provided for context only. Your endpoint can only influence the pipeline through the output schema. specifically the sections field.

Metadata Keys by Connector#

The keys present in metadata depend on the connector source. Below are a few examples:

Example

{
"document_id": "FILE_CONNECTOR__0376357d-6431-4082-b71a-9f83688f1f16",
"title": "Q4 2024 Refund Policy",
"semantic_identifier": "Q4 2024 Refund Policy",
"source": "confluence",
"sections": [
  {
    "text": "Our refund policy allows returns within 30 days...",
    "link": "https://wiki.example.com/pages/123456",
    "image_file_id": null
  },
  {
    "text": null,
    "link": null,
    "image_file_id": "846d6333-1a2b-4c5d-8e9f-0a1b2c3d4e5f"
  }
],
"metadata": {
  "space": ["HR"],
  "labels": ["policy", "finance"]
},
"doc_updated_at": "2024-10-01T12:00:00.000000+00:00",
"primary_owners": [
  { "display_name": "Alice Smith", "email": "alice@example.com" }
],
"secondary_owners": null
}

Output Schema#

A successful response from your endpoint must return HTTP 200 and a JSON body:

Example: Pass through unchanged#

  {
    "sections": [
      {
        "text": "Our refund policy allows returns within 30 days...",
        "link": "https://wiki.example.com/pages/123456",
        "image_file_id": null
      },
      {
        "text": null,
        "link": null,
        "image_file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    ],
    "rejection_reason": null
  }

Example: Rewrite content (PII redaction)#

  {
    "sections": [
      { "text": "Our refund policy allows returns within 30 days. Contact [REDACTED] for details." }
    ],
    "rejection_reason": null
  }

Example: Drop the document#

  {
    "sections": null,
    "rejection_reason": "Document contains restricted classification label."
  }

Authentication#

If you configured an API key when registering the hook, Onyx includes it in every request:

Authorization: Bearer <your-api-key>

Lambda Example#

You can use an AWS Lambda function as your hook endpoint by exposing it over HTTPS via a Lambda Function URL. This is the simplest way to deploy a hook without managing a server.

When Onyx calls your endpoint, the request arrives as an API Gateway-style event. Your handler reads the JSON body from event["body"], processes the document, and returns a response with a statusCode and a JSON-encoded body.

If you configured an API key on the hook, validate it against the Authorization header in the event before processing.

Lambda Example (Python)#

import json
import logging
import os

logger = logging.getLogger()
logger.setLevel(logging.INFO)

# Set the HOOK_API_KEY environment variable in your Lambda configuration.
# If not set, API key validation is skipped.
API_KEY = os.environ.get("HOOK_API_KEY")

def lambda_handler(event, context):
    # Validate API key if configured
    if API_KEY:
        auth = (event.get("headers") or {}).get("authorization", "")
        if auth != f"Bearer {API_KEY}":
            logger.warning("Unauthorized request. invalid or missing API key")
            return {"statusCode": 401, "body": json.dumps({"error": "Unauthorized"})}

    body = json.loads(event.get("body", "{}"))
    source = body.get("source", "")
    document_id = body.get("document_id", "")
    sections = body.get("sections", [])

    logger.info("Received document: id=%s source=%s sections=%d", document_id, source, len(sections))

    # Reject documents from the file connector
    if source == "file":
        logger.info("Rejecting document %s. file connector documents are not allowed", document_id)
        return {
            "statusCode": 200,
            "body": json.dumps({
                "sections": None,
                "rejection_reason": "File connector documents are not allowed.",
            }),
        }

    logger.info("Passing through document %s", document_id)
    return {
        "statusCode": 200,
        "body": json.dumps({"sections": sections}),
    }

Testing#

Use curl to test your Lambda Function URL before connecting it to Onyx.

Pass-through (non-file source):

curl -X POST https://<your-function-url> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
  "document_id": "confluence::page::123456",
  "title": "Q4 Refund Policy",
  "semantic_identifier": "Q4 Refund Policy",
  "source": "confluence",
  "sections": [{"text": "Our refund policy allows returns within 30 days.", "link": null, "image_file_id": null}],
  "metadata": {},
  "doc_updated_at": null,
  "primary_owners": null,
  "secondary_owners": null
}'

Rejected (file source):

curl -X POST https://<your-function-url> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
  "document_id": "FILE_CONNECTOR__abc123",
  "title": "Internal Doc",
  "semantic_identifier": "Internal Doc",
  "source": "file",
  "sections": [{"text": "Some content.", "link": null, "image_file_id": null}],
  "metadata": {},
  "doc_updated_at": null,
  "primary_owners": null,
  "secondary_owners": null
}'

Once the hook is connected, you can validate end-to-end by adding a File connector and uploading a document. After the connector syncs, search for content from that document in the chat window — if the hook is working correctly, the material should not appear in results since file connector documents are being rejected.

Document Push#

The Document Push hook point fires after each document is successfully indexed. Use it to push indexed content to an external destination such as a wiki, data warehouse, or audit log.

Unlike Document Ingestion (which runs before indexing and can modify or drop documents), this hook fires after the document has been written to the index. The response body is not used — any 2xx response is treated as success.

Document Push only fires for public connectors in single-tenant deployments, and only during incremental syncs — it does not fire during an initial index or a full re-index from the beginning.

Input Schema#

Onyx sends a POST request to your endpoint once per successfully indexed document with the following JSON body:

{
"document_id": "string",
"title": "string | null",
"content": "string",
"source": "string",
"url": "string | null",
"doc_updated_at": "string | null",
"metadata": { "key": ["string"] }
}

Example

{
"document_id": "confluence::page::789012",
"title": "Engineering Onboarding Guide",
"content": "Welcome to the engineering team. This guide covers...",
"source": "confluence",
"url": "https://wiki.example.com/pages/789012",
"doc_updated_at": "2025-03-15T09:30:00.000000+00:00",
"metadata": {
  "space": ["Engineering"],
  "labels": ["onboarding", "guide"]
}
}

Output Schema#

The response body is not used — any 2xx status code is treated as success. Your endpoint can return an empty body or any JSON object.

Authentication#

If you configured an API key when registering the hook, Onyx includes it in every request:

Authorization: Bearer <your-api-key>

Lambda Example#

You can use an AWS Lambda function as your hook endpoint by exposing it over HTTPS via a Lambda Function URL.

Lambda Example (Python)#

import json
import logging
import os

logger = logging.getLogger()
logger.setLevel(logging.INFO)

API_KEY = os.environ.get("HOOK_API_KEY")

def lambda_handler(event, context):
    if API_KEY:
        auth = (event.get("headers") or {}).get("authorization", "")
        if auth != f"Bearer {API_KEY}":
            return {"statusCode": 401, "body": json.dumps({"error": "Unauthorized"})}

    body = json.loads(event.get("body", "{}"))
    logger.info("Received document: id=%s title=%s", body.get("document_id"), body.get("title"))

    return {"statusCode": 200, "body": "{}"}

Testing#

Use curl to test your endpoint before connecting it to Onyx:

curl -X POST https://<your-function-url> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
  "document_id": "confluence::page::789012",
  "title": "Engineering Onboarding Guide",
  "content": "Welcome to the engineering team. This guide covers...",
  "source": "confluence",
  "url": "https://wiki.example.com/pages/789012",
  "doc_updated_at": "2025-03-15T09:30:00.000000+00:00",
  "metadata": { "space": ["Engineering"], "labels": ["onboarding"] }
}'

Query Processing#

The Query Processing hook point lets you intercept every user query before it enters the Onyx pipeline. Your endpoint receives the raw query and the user's identity, and can rewrite the query, reject it entirely, or pass it through unchanged.

It runs immediately after the user submits a message, before anything is saved to the database or sent to the LLM. This is the earliest possible point in the pipeline — no side effects have occurred yet.

Input Schema#

Onyx sends a POST request to your endpoint with the following JSON body:

{
"query": "What is our refund policy?",
"user_email": "alice@example.com",
"chat_session_id": "550e8400-e29b-41d4-a716-446655440000"
}

Output Schema#

A successful response from your endpoint must return HTTP 200 and a JSON body:

Example: Pass through unchanged#

  {
    "query": "What is our refund policy?",
    "rejection_message": null
  }

Example: Rewrite the query#

  {
    "query": "What is the refund policy for enterprise customers?",
    "rejection_message": null
  }

Example: Reject the query#

  {
    "query": null,
    "rejection_message": "This topic is restricted. Please contact your administrator."
  }

Authentication#

If you configured an API key when registering the hook, Onyx includes it in every request:

Authorization: Bearer <your-api-key>

Lambda Example#

You can use an AWS Lambda function as your hook endpoint by exposing it over HTTPS via a Lambda Function URL. This is the simplest way to deploy a hook without managing a server.

When Onyx calls your endpoint, the request arrives as an API Gateway-style event. Your handler reads the JSON body from event["body"], processes the query, and returns a response with a statusCode and a JSON-encoded body.

If you configured an API key on the hook, validate it against the Authorization header in the event before processing.

Lambda Example (Python)#

import json
import os

BLOCKED_KEYWORDS = ["ssn", "phone number"]

# Set the HOOK_API_KEY environment variable in your Lambda configuration.
# If not set, API key validation is skipped.
API_KEY = os.environ.get("HOOK_API_KEY")

def lambda_handler(event, context):
    # Validate API key if configured
    if API_KEY:
        auth = (event.get("headers") or {}).get("authorization", "")
        if auth != f"Bearer {API_KEY}":
            return {"statusCode": 401, "body": json.dumps({"error": "Unauthorized"})}

    body = json.loads(event.get("body", "{}"))
    query = body.get("query", "")

    # Reject queries containing blocked keywords
    for keyword in BLOCKED_KEYWORDS:
        if keyword.lower() in query.lower():
            return {
                "statusCode": 200,
                "body": json.dumps({
                    "query": None,
                    "rejection_message": "Your query contains restricted terms. Please contact your administrator.",
                }),
            }

    return {
        "statusCode": 200,
        "body": json.dumps({"query": query}),
    }

Testing#

Use curl to test your Lambda Function URL before connecting it to Onyx.

Pass-through (no blocked keywords):

curl -X POST https://<your-function-url> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
  "query": "What is our refund policy?",
  "user_email": "alice@example.com",
  "chat_session_id": "550e8400-e29b-41d4-a716-446655440000"
}'

Rejected (contains blocked keyword):

curl -X POST https://<your-function-url> \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-api-key>" \
-d '{
  "query": "What is the SSN format?",
  "user_email": "alice@example.com",
  "chat_session_id": "550e8400-e29b-41d4-a716-446655440000"
}'

Once the hook is connected, you can also validate the logic directly in the Nexus chat window. Try sending a query that contains a blocked keyword (e.g. "ssn" or "phone number") , you should see the rejection message instead of a response. Queries without blocked keywords should pass through normally.

Suggesting a New Hook Point#

If your use case requires a pipeline injection point that doesn't exist yet, open a GitHub issue describing:

• Where in the pipeline you need to inject logic (e.g. after retrieval, before document indexing)

• What your endpoint would receive. what context does it need to do its job?

• What your endpoint would return. how should Nexus change its behavior based on your response?

• Use cases. what problem does this solve? Are other customers likely to need the same point?

The Nexus team reviews proposals and implements hook points that have broad applicability. Once a hook point is added, Nexus commits to maintaining its payload structure, response format, and behavior. meaning it won't change in a breaking way without a proper deprecation process. Because of this long-term commitment, each proposal is evaluated carefully before being added.