Webhook trigger

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

Prerequisites

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

Endpoint

POST https://api.ingestly.ai/workflows/{workflowId}/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/workflows/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/workflows/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/workflows/3fa85f64-5717-4562-b3fc-2c963f66afa6/trigger",
    content
);

Python

import requests

url = "https://api.ingestly.ai/workflows/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 document’s ID and status: queued when a run has started, or held when the webhook trigger’s Run automatically setting is off and the document is held instead. See the API reference for the full response schema.

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`	Workflow not found or not active
`409`	Duplicate request: the `Idempotency-Key` has already been processed

Webhook trigger configuration

The webhook trigger node in your workflow 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
Run automatically: on by default. Turn it off to hold submitted documents instead of starting a run. Held documents wait under Inbox > Workflows, beneath this workflow, until you run them

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