WorqHat
Triggers

File Upload Trigger

Category
Trigger
Node Type
File-Based

Overview

The File Upload Trigger node starts a workflow automatically when a single file is uploaded through a form-data POST request. It serves as the entry point for workflows that depend on documents, images, audio, or other files uploaded by users or systems.

Description

Trigger workflow when a file is uploaded via form-data POST request.

This node listens for incoming multipart/form-data POST requests containing exactly one file.
It also accepts any number of additional non-file metadata fields (e.g., userId, category, description).

Typical use cases include:

  • PDF uploads for analysis or text extraction
  • Image uploads for recognition or classification
  • Audio/video uploads for transcription
  • Document ingestion pipelines

Once the request is received, the workflow begins immediately and exposes the uploaded file and metadata to downstream nodes.

Input Parameters

The File Upload Trigger node accepts:

  • One single file (mandatory)
  • Any number of simple text metadata fields (optional)
filefileRequired
The uploaded file that triggers the workflow. Must be provided in multipart/form-data. Only one file is supported.
Any metadata fieldstringOptional
Optional non-file key-value inputs such as userId, category, description, etc.
Example
userId, category, description
Instructions

This node accepts only multipart/form-data POST requests.
The file field is mandatory and must contain exactly one file.
Additional parameters must be plain string key-value pairs.
JSON bodies and nested objects are not supported.

File uploads must be sent as form-data, not JSON.

Keys should be simple strings (e.g., userId, category, description).
Values may be strings, numbers, or booleans.

All metadata inputs are optional; only the file field is required.

You can access the received values inside the workflow using: {{nodeId.input.<key>}}.

If a key is not provided in the request, it will default to null.

Access input data within the workflow using:

{{nodeId.input.<key>}}

Example:

{{fileUploadTrigger.input.file}}
{{fileUploadTrigger.input.userId}}

Output Parameters

This node does not produce any output parameters of its own.
It only exposes the uploaded file and metadata through {{nodeId.input.*}} for downstream nodes.

Accessing Data

You can access uploaded file and metadata values in other nodes using:

{{fileUploadTrigger.input.file}}
{{fileUploadTrigger.input.userId}}
{{fileUploadTrigger.input.category}}

Output Type

Output Type: None

The node does not define or emit any structured output type.
It only forwards the uploaded file and metadata as input fields accessible via {{nodeId.input.<key>}}.

Example Usage

Trigger Workflow with File Upload

Incoming API Request (Form-Data POST):

POST https://api.worqhat.com/flows/files/flow-idAuthorization: Bearer <YOUR_WORKFLOW_API_KEY>Content-Type: multipart/form-datafile: invoice_2025.pdfuserId: U001category: billing

Accessing Values Inside the Workflow:

{{fileUploadTrigger.input.file}}       → invoice_2025.pdf
{{fileUploadTrigger.input.userId}}     → "U001"
{{fileUploadTrigger.input.category}}    → "billing"

Example: Image Upload with Metadata

Incoming API Request:

POST https://api.worqhat.com/flows/files/flow-idAuthorization: Bearer <YOUR_WORKFLOW_API_KEY>Content-Type: multipart/form-datafile: product.jpgdescription: Product listing image

Accessing Values Inside the Workflow:

{{fileUploadTrigger.input.file}}         → product.jpg
{{fileUploadTrigger.input.description}}  → "Product listing image"

Example: Sending a File via cURL (Form-Data)

You can trigger the workflow by uploading a file using a multipart/form-data POST request.

curl -X POST "https://api.worqhat.com/flows/files/flow-id" \  -H "Authorization: Bearer <YOUR_WORKFLOW_API_KEY>" \  -H "Content-Type: multipart/form-data" \  -F "file=@/path/to/document.pdf" \  -F "userId=U001" \  -F "category=billing" \  -F "description=Quarterly invoice upload"

Example: Sending a File Using Postman

1

Create a New Request

Open Postman and click New → Request.

2

Set Method and URL

  • Method: POST
  • URL: https://api.worqhat.com/flows/files/flow-id
3

Select Body → Form-Data

  • Choose form-data
  • Add a field named file
  • Set its type to File
  • Upload the file to trigger the workflow
4

Add Metadata Fields

Add additional fields (Type: Text), e.g.:

  • userId: U001
  • category: billing
  • description: Quarterly invoice
5

Send the Request

Click Send to trigger the workflow.

6

Verify Workflow Execution

Check workflow logs or downstream outputs to ensure data was received.

How to Use in a No-Code Workflow

1

Add the File Upload Trigger Node

Insert it at the beginning of your workflow.

2

Define File Input

Ensure the trigger expects exactly one uploaded file.

3

Add Metadata Inputs

Add optional fields like userId, description, or category.

4

Connect to Processing Nodes

Link this node to extraction, analysis, or transformation nodes.

5

Test with a File Upload

Use a tool like Postman or cURL to send a test file upload to the workflow endpoint.

Example Using cURL

curl -X POST "https://api.worqhat.com/flows/files/flow-id" \  -H "Authorization: Bearer <YOUR_WORKFLOW_API_KEY>" \  -H "Content-Type: multipart/form-data" \  -F "file=@/path/to/document.pdf" \  -F "userId=U001" \  -F "category=billing"

Example Using Postman

  • Set Method: POST
  • Set URL: https://api.worqhat.com/flows/files/flow-id
  • Set Headers:
    • Authorization: Bearer <YOUR_WORKFLOW_API_KEY>
  • Go to Body → form-data
  • Add a field named file (Type: File) and select your file
  • Add additional fields (Type: Text), e.g.:
    • userId: U001
    • category: billing
  • Click Send to trigger the workflow.
6

Connect to Other Nodes

Link this trigger node to other nodes (e.g., Text Extraction, AI, Database, Email) to process, store, or react to the uploaded file automatically.

Best Practices

  • Ensure the file field is ALWAYS included.
  • Use meaningful filenames for easier tracking.
  • Validate file formats in downstream nodes.
  • Add metadata like userId or category when needed.
  • Avoid extremely large files.
  • Always send requests over HTTPS for secure communication.
  • Test your workflow endpoint thoroughly using tools like Postman or cURL before production use.

Do / Don't

Do
  • ✔️ Always send the file using multipart/form-data.
  • ✔️ Ensure the file field contains exactly one file.
  • ✔️ Include additional metadata fields as simple key-value text pairs.
  • ✔️ Validate file types and sizes in downstream processing nodes.
  • ✔️ Use meaningful names for files and metadata (e.g., invoiceNumber, userId).
  • ✔️ Test uploads using Postman, cURL, or the No-Code UI before deployment.
  • ✔️ Keep workflows modular—handle parsing, extraction, and analysis in proper nodes.
Don't
  • ❌ Don't send multiple files — only one file is supported.
  • ❌ Don't send JSON bodies — only form-data POST requests are accepted.
  • ❌ Don't send nested structured metadata — keep values simple text.
  • ❌ Don't use GET/PUT requests — only POST is valid.
  • ❌ Don't upload extremely large files unless downstream nodes can handle them.
  • ❌ Don't assume the trigger validates files — it only receives them; validation must be downstream.

Example Workflow Integration

Use Case: Automatically analyze uploaded documents.

  1. Trigger Node – File Upload Trigger (workflow begins when a file is uploaded)
  2. Text Extraction Node – Extracts text from PDF or image
  3. AI Node – Summarizes or classifies extracted content
  4. Email/Storage Node – Sends or stores processed results

Additional File Upload Use Cases

1. Automated Resume Screening

A user uploads:

{  "file": "resume.pdf",  "jobId": "JR-0923"}

The workflow extracts resume text, analyzes skills, and ranks the candidate.

2. Image-Based Product Tagging

An admin uploads:

{  "file": "product_photo.jpg",  "category": "shoes"}

The workflow runs image recognition and auto-tags the product.

3. Audio File Transcription

A system posts:

{  "file": "meeting_audio.mp3",  "uploadedBy": "teamLead"}

The workflow transcribes the audio, summarizes key points, and stores notes.

4. Document Compliance Check

A partner uploads:

{  "file": "contract_v3.docx",  "department": "legal"}

The workflow extracts text, checks compliance rules, and generates a report.

Common Errors

Missing file fieldErrorOptional
The form-data request did not include the 'file' field. It is required.
Invalid content typeErrorOptional
Only multipart/form-data is supported — JSON bodies are not allowed.
Multiple files providedErrorOptional
Only one file is supported. Sending multiple files will cause the request to fail.
Unsupported file formatErrorOptional
The next node(s) cannot handle the uploaded file type.