Webhook trigger

The webhook trigger lets you submit documents to a pipeline via API, enabling programmatic integration with your applications.

Prerequisites

A pipeline with a Webhook trigger node in its configuration
An API key with trigger permissions

Endpoint

POST https://api.ingestly.ai/pipelines/{pipelineId}/trigger

Authentication

Include your API key in the X-Api-Key header:

X-Api-Key: ing_your_api_key_here

See authentication for details on API key management.

Request

Send the document as multipart/form-data with the file in the file field.

cURL

curl -X POST "https://api.ingestly.ai/pipelines/3fa85f64-5717-4562-b3fc-2c963f66afa6/trigger" \
  -H "X-Api-Key: ing_your_api_key_here" \
  -F "file=@invoice.pdf"

JavaScript

const formData = new FormData();
formData.append("file", fileBlob, "invoice.pdf");

const response = await fetch(
  "https://api.ingestly.ai/pipelines/3fa85f64-5717-4562-b3fc-2c963f66afa6/trigger",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "ing_your_api_key_here",
    },
    body: formData,
  }
);

const result = await response.json();

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "ing_your_api_key_here");

using var content = new MultipartFormDataContent();
using var fileStream = File.OpenRead("invoice.pdf");
content.Add(new StreamContent(fileStream), "file", "invoice.pdf");

var response = await client.PostAsync(
    "https://api.ingestly.ai/pipelines/3fa85f64-5717-4562-b3fc-2c963f66afa6/trigger",
    content
);

Python

import requests

url = "https://api.ingestly.ai/pipelines/3fa85f64-5717-4562-b3fc-2c963f66afa6/trigger"
headers = {"X-Api-Key": "ing_your_api_key_here"}
files = {"file": ("invoice.pdf", open("invoice.pdf", "rb"), "application/pdf")}

response = requests.post(url, headers=headers, files=files)
result = response.json()

Response

A successful request returns the trigger result with details about the created run.

Idempotency

To prevent duplicate document submissions (for example, due to network retries), include an Idempotency-Key header with a unique GUID:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

If a request with the same idempotency key has already been processed successfully, the API returns 409 Conflict instead of creating a duplicate. The key is optional: if omitted, the request is processed normally without deduplication. Only successful (2xx) responses consume the key. If a request returns 4xx or 5xx, you can safely retry the same Idempotency-Key; the next successful retry is the one that locks the key in.

Error handling

Common errors:

Status	Cause
`401`	Missing or invalid API key
`400`	Unsupported document format or document exceeds size limit
`404`	Pipeline not found or not active
`409`	Duplicate request: the `Idempotency-Key` has already been processed

Webhook trigger configuration

The webhook trigger node in your pipeline can be configured with:

Allowed origins: restrict which origins can submit documents (CORS)
Accepted formats: limit accepted document formats
Max size (MB): set a maximum document size

See the API reference for the complete endpoint specification.

Getting started

Learn

Guides

Reference

Administration

Prerequisites

Endpoint

Authentication

Request

cURL

JavaScript

C#

Python

Response

Idempotency

Error handling

Webhook trigger configuration

​Prerequisites

​Endpoint

​Authentication

​Request

​cURL

​JavaScript

​C#

​Python

​Response

​Idempotency

​Error handling

​Webhook trigger configuration

Prerequisites

Endpoint

Authentication

Request

cURL

JavaScript

C#

Python

Response

Idempotency

Error handling

Webhook trigger configuration