> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ingestly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook trigger

> Submit documents to a pipeline programmatically via the HTTP API.

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](/admin/api-keys) 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](/api-reference/authentication) for details on API key management.

## Request

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

### cURL

```bash theme={null}
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

```javascript theme={null}
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\#

```csharp theme={null}
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

```python theme={null}
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

<Snippet file="error-response.mdx" />

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](/api-reference/trigger-webhook) for the complete endpoint specification.