HTTP File Trigger (Upload and Download)

Discover more about the HTTP File Trigger and how to use it on the Digibee Integration Platform.

The HTTP File Trigger can be used to:

Upload: Send large files (over 5 MB) to a pipeline via HTTP.
Download: Download large files using the GET method.

Below, you’ll learn how to configure the trigger for both purposes.

Parameters

Configure the trigger using the parameters below. Fields that support Double Braces expressions are marked in the Supports DB column.

Parameter

Description

Type

Supports DB

Default

Methods

Defines the methods accepted by the pipeline.

String

❌

POST, PUT, GET, PATCH and DELETE

Response Headers

Headers to be returned by the endpoint when the pipeline processing is complete. Special characters should not be used in keys, due to possible failures in proxies and gateways.

Key-value pairs

✅

N/A

Add Cross-Origin Resource Sharing (CORS)

If enabled, allows you to add CORS headers to be returned by the endpoint after the pipeline processing is complete. Use a comma (,) to separate multiple values in a header, without adding spaces before or after the comma. Avoid using special characters in header keys, as they can cause failures in proxies or gateways.

Boolean

❌

False

CORS Headers

Defines CORS specifically for the pipeline and its constraints.

To configure it globally, instead of individually in each pipeline, see the CORS HTTP Header policy.

Key-value pairs

❌

N/A

Form Data Uploads

Enables or disables the receipt of form data uploads (multipart form data).

Boolean

❌

True

Body Uploads

Enables or disables the receipt of body uploads.

Boolean

❌

True

Body Upload Content Types

Defines the content types allowed by the pipeline for body uploads.

String

❌

application/pdf, application/jpeg

Response Content Types

Defines the response content types allowed by the pipeline. For example, this setting determines the response format.

String

✅

text/xml, application/xml

Maximum Timeout

Maximum time (in milliseconds) that the pipeline takes to process information before returning a response. Limit: 900000.

If processing exceeds this limit, the request is finished and returns a 500 status code without a response body.

Integer

❌

30000

Maximum Request Size

Defines the maximum size of the file in the upload request (in MB). Maximum: 100 MB.

Integer

❌

100

External API

If enabled, publishes the API to an external gateway.

Boolean

❌

True

Internal API

If enabled, publishes the API to an internal gateway.

Boolean

❌

False

mTLS enabled API

If enabled, the API is published to a dedicated mTLS gateway, with a different access host.

The pipeline can have both External API and Internal API options enabled. However, it’s recommended to keep them disabled.

This parameter doesn’t support API Key, JWT, or Basic Auth. To enable them in your realm, contact Support.

Boolean

❌

False

API Key

If enabled, the endpoint can only be accessed if an API key has been previously configured in the Digibee Integration Platform.

Boolean

❌

False

Token JWT

If enabled, the token for API consumption will be requested.

Boolean

❌

False

Basic Auth

If enabled, the endpoint can only be consumed if a Basic Auth setting is present in the request.

This setting can be registered beforehand through the Consumers page in the Digibee Integration Platform.

Boolean

❌

False

Additional API Routes

If enabled, allows you to add new routes.

Boolean

❌

False

Remove Digibee Prefix from Route

Removes the default Digibee route prefix /pipeline/{realm}/v{n}from the pipeline route.

Available only when External API and Internal API parameters are disabled, and mTLS enabled API and Additional API Routes parameters are enabled.

Boolean

❌

False

Routes

Defines custom routes.

String

❌

N/A

Rate Limit

If enabled, a rate-limiting will be applied to the API gateway.

Available if API Key or Basic Auth is enabled.

Boolean

❌

False

Limit by

Defines the entity to which the limits will be applied.

String

❌

API

Aggregate by

Defines the entity for aggregating the limits. Options: Consumers and Credential (API Key, Basic Auth).

String

❌

Consumer

Options

Defines the limit of requests allowed within a time interval.

Options for limit and interval

❌

N/A

Interval

Defines the time interval for the request limit. Options: second, minute, hour, day, and month.

String

❌

second

Limit

Defines the maximum number of requests users can make within the specified time interval.

Integer

❌

N/A

Allow Redelivery Of Messages

If enabled, allows messages to be redelivered in case of a Pipeline Engine failure.

Boolean

❌

False

HTTP File Trigger in action

Upload

Scenario 1: `POST` with `multipart/form-data` content type of file

Suppose you want to send a file larger than 5 MB. You can call a pipeline endpoint configured with an HTTP File Trigger using a POST request with the multipart/form-data content type. This allows the pipeline to process the file. Follow these steps:

Enable the Form Data Uploads option in the HTTP File Trigger.
Deploy the pipeline.
Create a Consumer and configure it to have access to the pipeline.
Call the pipeline using the following cURL command:

curl -d “@file_name” https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token'

file_name: Refers to a local file.
realm_name: Refers to the realm where the pipeline is located.
generated_token: Refers to the API Key generated by the recently created consumer.

The pipeline will receive an array files[] containing:

fileName
param
contentType

This allows the file to be referenced and accessed from the pipeline:

{
  "body": null,
  "form": {},
  "headers": {
  ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {      
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"    
    }  
  ]
}

Scenario 2: `POST` with `multipart/form-data` content type of multiple files

Suppose you have multiple files larger than 5 MB. You can call a pipeline endpoint configured with an HTTP File Trigger using a POST request with the multipart/form-data content type, allowing the pipeline to process these files. Follow these steps:

Enable the Form Data Uploads option in the HTTP File Trigger.
Deploy the pipeline.
Create a Consumer and configure it to have access to the pipeline.
Call the pipeline using the following cURL command:

curl -F dgbfile1=@file_name1 -F dgbfile2=@file_name2 https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'

file_name1: Refers to a local file.
file_name2: Refers to a local file.
realm_name: Refers to the realm where the pipeline is located.
generated_token: Refers to the API Key generated by the recently created consumer.

The pipeline will receive an array files[] containing:

fileName
originalFileName
param
charset
contentLength
contentType

This allows the files to be referenced and accessed from the pipeline:

{
  "body": "",
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "multipart/form-data; boundary=------------------------b3c985803b952f2c",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "96f3ecb2-1c72-4980-9f01-6f44cafc719f",
      "originalFileName": "file1",
      "param": "dgbfile1",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    },
    {
      "fileName": "58fb844f-a1d1-4788-b9b4-30df4b69165e",
      "originalFileName": "file2",
      "param": "dgbfile2",
      "contentType": "application/octet-stream",
      "charset": "UTF-8",
      "contentLength": 5242880
    }
  ]
}

Scenario 3: `POST` with any content type and body with more than 5MB

Suppose you have multiple files larger than 5 MB. You can call a pipeline endpoint configured with an HTTP Trigger using a POST request with any content type, allowing the pipeline to process these files. Follow these steps:

Enable the Body Uploads option in the HTTP File Trigger.
Deploy the pipeline.
Create a Consumer and configure it to have access to the pipeline.
Call the pipeline using the following cURL command:

curl -d '@file_name1' https://godigibee.io/pipeline/realm_name/v1/http-file-upload -v -H 'apikey: generated_token'

The pipeline will receive an array files[] containing:

fileName
param
charset
contentType

This allows the files to be referenced and accessed from the pipeline:

{
  "body": null,
  "form": {},
  "headers": {
    ...
  },
  "queryAndPath": {},
  "method": "POST",
  "contentType": "application/pdf",
  "path": "/pipeline/realm_name/v1/http-file-upload",
  "files": [
    {
      "fileName": "55acdc09-c0fc-4f6a-b3ee-f4199076b0c4",
      "param": "body",
      "contentType": "application/pdf"
    }
  ]
}

Download

Scenario: `GET` with any content type

Suppose you have a file larger than 5 MB. You can call a pipeline endpoint configured with an HTTP Trigger using a GET request with any content type. The pipeline receives and processes the file, returning it according to the output content type and its original content. Follow these steps:

Include the GET method and specify the Response Content Types in the HTTP File Trigger.
Add a File Reader connector to the pipeline to search the file to be processed. For example, you can configure a WGet connector to retrieve a file of a URL sent to the endpoint during a call.
Insert a JSON Generator as the last step in your pipeline to produce a JSON in the following format:

{ 
    "file": "file-download.pdf",
    "Content-Type": "application/pdf"
}

Deploy the pipeline.
Create a Consumer and configure it to have access to the pipeline.
Call the pipeline using the following cURL command:

curl https://godigibee.io/pipeline/realm_name/v1/pipeline_name -v -H 'Content-Type: application/pdf' -H 'apikey: generated_token' -H 'urlDownload: http://url/path'

realm_name: Refers to the realm where the pipeline is located.
generated_token: Refers to the API Key generated by the recently created consumer.
urlDownload: Parameter sent to the WGet connector to populate the URL field. The attribute is optional but allows a more flexible approach using Double Braces. It works seamlessly if you define the path directly within the WGet connector.

HTTP File Trigger response

Upload response

To define the pipeline response format, add a transformer connector, such as the Transformer (JOLT), as the final step in the pipeline and configure the desired response.

{  
    "body": "<xml>Output 1</xml>",  
    "code": 200,  
    "Content-Type": "application/xml"
}

Response limitations for payloads above 5 MB

For payloads larger than 5 MB, it’s recommended that the pipeline returns a file instead of a payload. Use the File Writer connector to generate the file, and reference it in the pipeline response using the file property rather than body:

{
"file": {{ message.fileName }},
"code": 200,
"Content-Type": "application/json"
}

Download response

To define the pipeline response format, add a transformer connector, such as the Transformer (JOLT), as the final step in the pipeline and configure the desired response:

{  
    "file": "file-download.pdf",  
    "code": 200,  
    "Content-Type": "application/pdf"
}

The HTTP File Trigger can also respond with non-file bodies, similar to the HTTP Trigger. To do so, the last step of the pipeline must have this structure:

{ 
    "body": "information that will be written in the endpoint output", 
    "Content-Type": "body content type", 
    "code": <a HTTP return code>
}

Response properties

The same response structure applies to both upload and download scenarios.

code: HTTP status code to be returned by the endpoint after a request is finished.
body: Response message body. This field must be a string. If you need to send JSON data, use the TOSTRING function.
content-type: Content type of the response body. All content types are supported, but they must be declared in the Response Content Types field.

Best practices

Global configuration for authentication

A global configuration parameter enforces authentication for all pipelines using the HTTP File Trigger. When enabled, pipelines can only be published if at least one authentication method (API Key or Basic Auth) is configured.

Remove Digibee Prefix from Route

When removing the default prefix and defining the route through the Additional API Routes parameter, make sure not to use a route already assigned to another pipeline. If multiple major versions of the same pipeline exist, remember that route versioning must be managed manually, as there is no automatic versioning path (for example: /pipeline/realm/v1/).

Rate Limit

Enable the Rate Limit parameter to restrict the number of API requests within a specific time interval. Use the following configuration:

Limit by: API
Aggregate by: Credential (API Key, Basic Auth)
Options:
- Interval: second → Limit: 100
- Interval: minute → Limit: 1000
- Interval: hour → Limit: 5000

If the API includes additional paths, the limit applies to all of them collectively. To activate Rate Limit, the API must use an API key or Basic Auth, allowing aggregation by either groups of credentials (Consumer option) or individual credentials (Credential option).

If multiple interval parameters have the same value, only one is considered. The Limit parameter must always be greater than zero. Incorrect or incomplete rate limiting settings are ignored, and a warning log is generated. You can view this log on the Pipeline Logs page.

PreviousHTTP Trigger NextREST Trigger

Last updated 3 days ago

Was this helpful?

Parameters

HTTP File Trigger in action

Upload

Scenario 1: POST with multipart/form-data content type of file

Scenario 2: POST with multipart/form-data content type of multiple files

Scenario 3: POST with any content type and body with more than 5MB

Download

Scenario: GET with any content type

HTTP File Trigger response

Upload response

Response limitations for payloads above 5 MB

Download response

Response properties

Best practices

Global configuration for authentication

Remove Digibee Prefix from Route

Rate Limit

Scenario 1: `POST` with `multipart/form-data` content type of file

Scenario 2: `POST` with `multipart/form-data` content type of multiple files

Scenario 3: `POST` with any content type and body with more than 5MB

Scenario: `GET` with any content type