> For the complete documentation index, see [llms.txt](https://karini-ai.gitbook.io/karini-ai-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://karini-ai.gitbook.io/karini-ai-documentation/recipes/workflow-recipe/webhook-recipe.md). # 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** ](/karini-ai-documentation/recipes/workflow-recipe/set-up-workflow-recipe.md)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: ` **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** ```bash curl -X POST "https://app.karini.ai/api/webhook/recipe/{YOUR_RECIPE_ID}" \ -H "Content-Type: application/json" \ -H "x-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** ```json { "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** ```json { "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** ```json { "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** ```json { "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: ` **Headers** | Header | Required | Value | Description | | ------------- | -------- | ------------------ | ---------------------------------------- | | `accept` | No | `application/json` | Response format requested by the client. | | `x-api-token` | Yes | `` | 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 ```bash 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: ` **Headers** | Header | Required | Value | | ------------- | -------- | ------------------ | | `accept` | No | `application/json` | | `x-api-token` | Yes | `` | #### 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 ```bash curl -X GET \ "https://staging.karini.ai/api/webhook/recipe/692d8f13e735ad6e13b9ee1a?limit=10" \ -H "accept: application/json" \ -H "x-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** ](/karini-ai-documentation/dataset-export.md#export-from-webhook-history)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.
\