Webhook recipe

A webhook recipe is a workflow that starts with a Webhook node and can be invoked externally via API. It allows external systems to initiate a recipe run and, optionally, include input data in the request payload. For guidance on creating a webhook recipe, refer to the Set up workflow recipe section.

Webhook Recipe Invocation API

The Webhooks API provides the capability to invoke a Webhook Recipe, monitor individual webhook executions, and retrieve webhook request history for a given recipe.

1. Invoke a Webhook Recipe (Create Webhook Request)

Use the following curl command to invoke a webhook recipe via the Webhook Invocation API.

Endpoint

POST /api/webhook/recipe/{RECIPE_ID}

Base URL https://app.karini.ai

Authentication

This API uses an API token passed via header:

• Header: x-api-token: <YOUR_API_TOKEN>

Headers

Header	Required	Value
Content-Type	Yes	application/json
x-api-token	Yes	Your API token

Request Parameters

Field	Type	Required	Description
RECIPE_ID	string	Yes	The ID of the recipe you want to run.
content_type	string	Yes	Type of the file (e.g., application/pdf, text/plain).
file_name	string	Yes	Name of the file as it should appear in processing.
file_content	string	Conditional	Base64-encoded file content. Use this when uploading the file inline.
file_path	string	Conditional	Remote path/URI to the file (example: s3://bucket/path). Use this when the file is already stored remotely.
text	string	Conditional	Plain text content (typically used when content_type is text/plain).

Request payload

curl -X POST "https://app.karini.ai/api/webhook/recipe/{YOUR_RECIPE_ID}" \
  -H "Content-Type: application/json" \
  -H "x-api-token: <<YOUR_API_TOKEN>>" \
  -d '{
    "files": [
      {
        "content_type": "application/pdf",
        "file_name": "test1.pdf",
        "file_content": "(base64data)"
      },
      {
        "content_type": "application/pdf",
        "file_name": "test2.pdf",
        "file_path": "s3://bucket/path"
      },
      {
        "content_type": "text/plain",
        "file_name": "test.txt",
        "text": "this is a plain text"
      }
    ],
    "input_message": "Provide your request",
    "metadata": {}
  }'

---

Example payloads

1) Upload a PDF as base64

{
  "files": [
    {
      "content_type": "application/pdf",
      "file_name": "document.pdf",
      "file_content": "JVBERi0xLjQKJc..."
    }
  ],
  "input_message": "Summarize this document.",
  "metadata": { "requestId": "abc-123" }
}

2) Reference a file stored in S3

{
  "files": [
    {
      "content_type": "application/pdf",
      "file_name": "invoice.pdf",
      "file_path": "s3://my-bucket/invoices/invoice.pdf"
    }
  ],
  "input_message": "Extract totals and vendor info.",
  "metadata": { "customerId": "cust_001" }
}

3) Send plain text

{
  "files": [
    {
      "content_type": "text/plain",
      "file_name": "notes.txt",
      "text": "Meeting notes: finalize scope by Friday..."
    }
  ],
  "input_message": "Turn these notes into action items.",
  "metadata": {}
}

Response

Returns request_id for tracking processing status.

Response Body

Field	Type	Description
batch_status	string	Current status of the batch execution. Example: inProcess.
request_id	string	Unique identifier for this webhook execution request. Use this to track or fetch results later.
recipe_id	string	The recipe ID that was triggered .

Example Success Response

{
  "batch_status": "inProcess",
  "request_id": "6978913dcd248069899431a4",
  "recipe_id": "67500911de0df8d8ea5bc72b"
}

2.Monitor and Retrieve Results

Get Request Status

Retrieves the current status and details of a submitted webhook request, identified by request_id.

Endpoint

GET /api/webhook/request/{REQUEST_ID}

Base URL (staging) https://app.karini.ai

Authentication

Pass your API token in the request header:

• x-api-token: <YOUR_API_TOKEN>

Headers

Header	Required	Value	Description
accept	No	application/json	Response format requested by the client.
x-api-token	Yes	<YOUR_API_TOKEN>	API token for authentication.

Request Parameters

Parameter	Type	Required	Description
REQUEST_ID	string	Yes	The request ID returned by the webhook trigger API (e.g., request_id).

Request payload

curl -X GET "https://app.karini.ai/api/webhook/request/{REQUEST_ID}" \
 -H "accept: application/json" \
 -H "x-api-token: {YOUR_API_TOKEN}"

---

Response

This endpoint typically returns the current processing state and (when available) the final output for the request.

{
  "request_id": "6979b731e679ba7451721a78",
  "status": "success",
  "created": "2026-01-28T07:13:53.712Z",
  "input": "can u give me the purchase order number",
  "response": "The purchase order number is 1010957.",
  "metadata": {
    "user_context": {
      "id": "673cef0fbb92a0ffa87784d1"
    },
    "datetime": "2026-01-28T07:13:53.711Z",
    "message_url": "https://app.karini.ai/recipe/692d8f13e735ad6e13b9ee1a/history/?_id=6979b731e679ba7451721a78"
  },
  "full_response": {
    "batch_status": "success",
    "response": {
      "success_count": 1,
      "failure_count": 0,
      "results": [
        {
          "status": "success",
          "file_path": "unknown",
          "final_answer": "The purchase order number is 101015.",
          "sink_output_location": [],
          "execution_time_ms": 1083.7611780007137
        }
      ],
      "error": ""
    }
  }
}

Each record contains the following top-level fields:

Field	Type	Description
request_id	string	Unique identifier for the webhook execution request.
status	string	High-level request status (e.g., success, inProcess, failed).
created	string (ISO 8601)	Timestamp when the request was created.
input	string	The input message used when triggering the recipe (input_message).
response	string	User-friendly final answer/summary (may be empty while processing).
metadata	object	Additional context/tracking info (user context, timestamps, UI link).
full_response	object	Detailed execution output including batch status and per-item results.

3.List Webhook Requests

Retrieves a list of webhook requests that are associated with a specific recipe, identified by recipe_id.

Endpoint

GET /api/webhook/recipe/{RECIPE_ID}

Base URL (staging) https://app.karini.ai

Authentication

• Header: x-api-token: <YOUR_API_TOKEN>

Headers

Header	Required	Value
accept	No	application/json
x-api-token	Yes	<YOUR_API_TOKEN>

Request parameters

Parameter	Type	Required	Description
RECIPE_ID	string	Yes	The recipe identifier whose webhook request history you want to fetch.

Query Parameters

Parameter	Type	Required	Description
limit	number	Optional	The maximum number of webhooks to return. Default is 10.

Request payload

curl -X GET \
  "https://staging.karini.ai/api/webhook/recipe/692d8f13e735ad6e13b9ee1a?limit=10" \
  -H "accept: application/json" \
  -H "x-api-token: <<YOUR_API_TOKEN>>" \  

Response

This endpoint typically returns a list of webhook execution records for the recipe (most recent first), usually including:

[
  {
    "request_id": "6979b731e679ba7451721a78",
    "status": "success",
    "created": "2026-01-28T07:13:53.712Z",
    "input": "can u give me the purchase order number",
    "response": "The purchase order number is 1010957.",
    "metadata": {
      "user_context": { "id": "673cef0fbb92a0ffa87784d1" },
      "datetime": "2026-01-28T07:13:53.711Z",
      "message_url": "https://app.karini.ai/recipe/692d8f13e735ad6e13b9ee1a/history/?_id=6979b731e679ba7451721a78"
    },
    "full_response": {
      "batch_status": "success",
      "response": {
        "success_count": 1,
        "failure_count": 0,
        "results": [
          {
            "status": "success",
            "file_path": "unknown",
            "final_answer": "The purchase order number is 1010111.",
            "sink_output_location": [],
            "execution_time_ms": 1083.7611780007137
          }
        ],
        "error": ""
      }
    }
  }
]

Each record contains the following top-level fields:

Field	Type	Description
request_id	string	Unique identifier for the webhook execution request.
status	string	High-level request status (e.g., success, inProcess, failed).
created	string (ISO 8601)	Timestamp when the request was created.
input	string	The input message used when triggering the recipe (input_message).
response	string	User-friendly final answer/summary (may be empty while processing).
metadata	object	Additional context/tracking info (user context, timestamps, UI link).
full_response	object	Detailed execution output including batch status and per-item results.

Webhook History (UI)

The Webhook History page serves as the operational log for a webhook recipe, offering a searchable and filterable view of every webhook execution. Each row represents a single request-level run and includes key details such as Request ID, recipe version, status, timestamps, inputs/outputs, errors, and supporting artifacts like attachments, webhook payloads, and trace diagnostics. Use this view to track and audit executions, validate which recipe version processed a request, troubleshoot failures, and perform operational actions such as resubmitting requests or exporting datasets.

Accessing Webhook History

To review execution outputs, traces, and request-level details for a webhook recipe:

1. From the left navigation menu, open Recipe.

2. Select the required Webhook Recipe from the list.

3. On the right side of the recipe page, click Action and choose Webhook History.

You’ll be redirected to the History page, which is available under the Activity Dashboard tab.

Column	Description
Request Id	Unique identifier for the execution. Can be used to retrieve request details via APIs such as GET /api/webhook/request/{request_id}.
Recipe Version	Version of the recipe that processed the webhook request. Useful for comparing outputs across recipe updates.
Status	Execution outcome (e.g., success, failed). Failures typically include details in Error.
Question	Operation label or prompt associated with the execution (e.g., Extract PO, Summarize documents).
Answer	Primary output returned by the recipe. Long responses may be truncated in the table view.
Error	Error message/details when execution fails. A dash (-) indicates no error.
Files	Files associated with the execution (typically input documents). File names appear as clickable links.
Metadata	Execution context displayed as JSON (e.g., user_context, internal references, timestamps).
Created	Timestamp indicating when the execution started.
Updated	Timestamp indicating when the execution record was last updated (e.g., after completion or status change).
Tokens	Token usage for the execution (when applicable). Supports usage monitoring and cost analysis.
Webhook Input	Captured webhook payload or input reference (typically structured/JSON). May include file attributes such as name, type, and path.
View	When the Online Evaluation option is enabled for nodes, the View button provides access to the evaluation report for each response. The report includes scores for each evaluation metric, along with a detailed reasoning summary explaining the assessment results.
View Trace	Provides a comprehensive, end-to-end trace of the recipe execution including tool invocation sequence, LLM interaction details, and token utilization.

Filter by

The Filter by control enables users to refine the Activity Dashboard results by applying specific criteria so the table displays only the most relevant requests.

• Date Range: Limit results to a specific time window.

• Status: Filter by outcome (e.g., success,in progress, failed)

• Online Evaluation Filters: Apply evaluation/metric-based conditions

• Guardrail Filters: Filter by guardrail or policy-trigger conditions

Action Menu

The Webhook History allows you to select one or more executions using the checkbox column on the left. After selection, the Action menu becomes available and provides the following operations:

Export Dataset Exports the selected execution records for offline analysis and reporting. For additional details, refer to the Dataset Export section.

Resubmit Request Re-initiates processing for the selected request(s). This is commonly used after updating a recipe version to re-run previously received requests against the latest configuration.