REST V2

Learn how to call external HTTP endpoints and configure the REST V2 connector on the Digibee Integration Platform.

Overview

REST V2 makes calls to HTTP endpoints, supporting actions such as GET, POST, PUT, and DELETE. t uses Double Braces expressions to compose the URL, headers, query parameters, and message body, allowing direct access to pipeline data.

You can configure the connector manually or import its settings from a cURL command or an OpenAPI specification, reducing setup time and the risk of configuration errors.

Importing from cURL or OpenAPI

When integrating an external API, you can import its contract directly into the REST V2 connector instead of configuring each field manually. The connector supports two import formats:

cURL: A command-line tool for making HTTP requests. If you already have a cURL command for the API you want to call, you can paste it directly into the connector.
OpenAPI: A standard specification format (JSON or YAML) that describes an API's endpoints, methods, parameters, and request structure. Most APIs publish an OpenAPI spec in their developer documentation.

To import a configuration:

In the REST V2 connector configuration page, click Import in the upper right corner and select either cURL or OpenAPI.
Provide the input:
- For cURL: Paste your cURL command. The connector supports -X, -H, -d, -u, and -b flags.
- For OpenAPI: Drop your OpenAPI contract in JSON or YAML format.
Click Apply.

Digibee parses the input and automatically populates the following fields:

URL: The base URL and path.
Verb: The HTTP method (GET, POST, PUT, DELETE, PATCH, and HEAD).
Headers: All headers defined in the contract.
Query Params: Query parameters defined in the spec.
Body: The request body structure.

Importing will overwrite all current fields in the connector.

After importing, review the populated fields and configure any dynamic values your pipeline requires using Double Braces expressions.

Parameters

The table below lists all configuration parameters for the connector. Parameters that support Double Braces expressions are marked with ✅ in the Supports DB column.

The Visible when column indicates parameters that only appear in the interface after a condition is met; parameters that are always visible are indicated with —.

This connector supports Alias, a parameter that saves the connector's output so it can be referenced later in the pipeline through Double Braces expressions.

Connection

Parameter

Description

Data type

Supports DB

Default

Visible when

URL

Address that will receive the HTTP call. Supports Double Braces, but account references are not allowed.

String

✅

https://viacep.com.br/ws/{{ DEFAULT(message.$.cep, "04547-130") }}/json/

—

Headers

All headers required for the call (for example, Content-Type: application/json). Supports Double Braces for both key and value fields. Account references are only allowed in value fields.

Key-value pairs

✅

Content-Type: application/json

—

Query Params

Query parameters required for the call. Supports Double Braces only for value fields.

Key-value pairs

✅ (values only)

N/A

—

Verb

The HTTP method (GET, POST, PUT, DELETE, PATCH, and HEAD).

String

❌

GET

—

Send A File

If enabled, sends a file in place of the body.

Boolean

❌

false

Verb is POST, PUT, DELETE, or PATCH

File Name

File name or full file path (for example, tmp/processed/file.txt).

String

✅

N/A

Send A File is enabled

Body

The body of the request. Click Write with AI to get AI support.

JSON

✅

N/A

Verb is POST, PUT, DELETE, or PATCH

Authentication

Parameter

Description

Data type

Supports DB

Default

Visible when

Use Dynamic Account

If enabled, uses the account dynamically; otherwise, uses it statically.

Boolean

❌

false

—

Scoped

If enabled, isolates the stored account from other sub-processes. Not supported for accounts used in headers or body. To learn more, read the Dynamic Accounts documentation.

Boolean

❌

false

Use Dynamic Account is enabled

Account Name

Account name generated dynamically through the Store Account connector.

String

❌

N/A

Use Dynamic Account is enabled

Account

Account used by the connector. Learn more in the Using accounts section.

String

❌

N/A

Use Dynamic Account is disabled

Custom Account #1

Account whose credentials can be referenced in any Double Braces-supported field through {{ account.custom-1.<field> }}. Learn more in the Using custom accounts section.

String

❌

N/A

—

Custom Account #2

Account whose credentials can be referenced in any Double Braces-supported field through {{ account.custom-1.<field> }}. Learn more in the Using custom accounts section.

String

❌

N/A

—

Timeouts

Learn more in the Configuring the timeouts section.

Parameter

Description

Data type

Supports DB

Default

Connect Timeout

Maximum time to establish a connection with the server, in milliseconds (includes DNS, TCP handshake, and TLS when applicable).

Integer

❌

30000

Read Timeout

Maximum time to wait for a response after the connection is established, in milliseconds.

Integer

❌

30000

Write Timeout

Maximum time to send the request body to the server, in milliseconds.

Integer

❌

30000

Call Timeout

Total time allowed for the entire request (connect, write, read), in milliseconds.

Integer

❌

30000

Error handling

Parameter

Description

Data type

Supports DB

Default

Stop On Client Error

If enabled, interrupts pipeline execution on a 4xx HTTP error.

Boolean

❌

false

Stop On Server Error

If enabled, interrupts pipeline execution on a 5xx HTTP error.

Boolean

❌

false

Response

Parameter

Description

Data type

Supports DB

Default

Visible when

Override Response Charset

If enabled, replaces the charset returned by the endpoint with the value specified in Response Charset.

Boolean

❌

false

—

Response Charset

Charset to apply.

String

❌

UTF-8

Override Response Charset is enabled

Advanced

These parameters are only available when Advanced Settings is enabled.

Parameter

Description

Data type

Supports DB

Default

Visible when

Raw Mode

If enabled, receives or sends a non-JSON payload.

Boolean

❌

false

—

Raw Mode As Base64

If enabled, returns the response encoded in Base64.

Boolean

❌

false

Raw Mode is enabled

Save As Local File

If enabled, saves the response as a file in the local pipeline directory.

Boolean

❌

false

—

Response File Name

File name or full file path (for example, tmp/processed/file.txt). Supports Double Braces, but account references are not allowed.

String

✅

N/A

Save As Local File is enabled

Allow Insecure Endpoints

If enabled, allows calls to HTTPS endpoints with invalid certificates.

Boolean

❌

false

—

Enable Retries

If enabled, retries the request after server errors.

Boolean

❌

false

—

Number Of Retries

Maximum number of retry attempts before giving up.

Integer

❌

0

Enable Retries is enabled

Time To Wait Between Retries

Wait time between retry attempts, in milliseconds.

Integer

❌

0

Enable Retries is enabled

Compress Body With GZIP

If enabled, compresses the request body using GZIP.

Boolean

❌

false

—

Force HTTP 1.1

If enabled, forces the request to use HTTP 1.1.

Boolean

❌

false

—

Disable Connection Pooling

If enabled, does not reuse connections. Recommended for endpoints with connection reuse issues.

Boolean

❌

false

—

Invalidate SSL Sessions On Every Call

If enabled, invalidates SSL sessions on every request. Recommended for endpoints with SSL session reuse issues. Activating this option makes the connector single-threaded.

Boolean

❌

false

—

Enable Follow Redirect

If enabled, automatically follows redirects for 302 responses. If disabled, returns the original 302 response for inspection before the redirect.

Boolean

❌

true

—

Documentation

Parameter

Description

Data type

Supports DB

Default

Documentation

Space for documenting connector configuration details and business rules.

String

❌

N/A

Messages flow

Input

The message body supports both static values and Double Braces expressions. This does not apply to GET requests.

{
    "id": {{ DEFAULT(message.customer.id, UUID()) }},
    "name": {{ message.customer.name }},
    "type": "1"
}

Output

Default response when the call succeeds.

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {},
    headers: {}
}

Returned when Save As Local File is enabled. The response body contains the name of the saved file.

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {
        file: "name of the file defined in the Response File Name property"
    },
    headers: {}
}

REST V2 in action

Configuring the timeouts

Connect timeout

Defines the maximum time allowed to establish a connection with the server. If the server is unavailable or slow to accept the connection, the request fails after this timeout.

Example: The server takes longer than 10 seconds to complete the handshake. The connection fails due to a timeout.

Read timeout

Specifies the maximum time to wait for a response after the request has been sent. Prevents the pipeline client from waiting indefinitely for data.

Example: The server accepted the connection but takes more than 15 seconds to start responding. A timeout error is returned.

Write timeout

Sets the maximum time allowed to send the request body to the server. Particularly relevant for requests with large payloads, such as file uploads.

Example: Uploading a file takes more than 30 seconds. The request fails due to a write timeout.

Call timeout

Defines the total timeout for the entire HTTP call, including connection, writing, and reading phases. If the combined duration exceeds this value, the request is aborted.

Example: You configure a 60-second timeout for the entire operation. If connecting, sending, and receiving together exceed this limit, the request is canceled.

Sending a binary file

To send a binary file through REST V2, provide:

The destination endpoint in URL
The content type (MIME type of the file) in the header, for example, application/pdf
The path where the file can be found in the File Name field

Making requests with content-type: multipart/form-data

Set the Content-Type: multipart/form-data header in the connector. When you select any HTTP verb other than GET, a body field appears for you to define the payload.

To specify fields:

{
  "fields": {
    "field_name1": "field_value_1",
    "field_name2": "field_value_2"
  }
}

To specify files:

{
  "files": {
    "file_field_name1": "path_to_file_1",
    "file_field_name2": "path_to_file_2"
  }
}

You can combine both structures and use Double Braces expressions for dynamic values.

Making requests with content-type: application/x-www-form-urlencoded

Set the Content-Type: application/x-www-form-urlencoded header in the connector. When you select any HTTP verb other than GET, a body field appears for you to define the payload.

Example:

{
  "field_name1": "field_value_1",
  "field_name2": "field_value_2"
}

Using accounts

REST V2 supports three account parameters, each with a different behavior:

Account: The connector automatically prepares the request with the account credentials according to the authentication technology.
Custom Account #1 and Custom Account #2: Can only be used to reference credential values in other fields through Double Braces, for example {{ account.custom-1.value }}.

The Account parameter always takes precedence over custom accounts.

The table below describes how the connector prepares the authorization for each supported account type.

Account type

How the connector handles authorization

API Key

Appends URL-PARAM-NAME and API-KEY as query parameters: https://www.address.com?<URL-PARAM-NAME>=<API-KEY>

AWS V4

Generates AWS authentication headers and signs the message using the AWS Signature Version 4 algorithm. Check the AWS service documentation for any additional required headers or parameters.

Basic

Encodes USERNAME and PASSWORD in Base64 and adds an authorization header: Authorization: Basic <ENCODED-INFORMATION>

Certificate Chain

Uses the provided chain to validate and establish a secure connection with the API server.

Custom Auth Header

Creates a custom header using HEADER-NAME and HEADER-VALUE: <HEADER-NAME>: <HEADER-VALUE>

Google Key

Generates a Google authentication token and adds an authorization header: Authorization: Bearer <GOOGLE-JWT-TOKEN>. Check the Google service documentation for any additional required headers or parameters.

OAuth 2

Behavior varies by provider. For Microsoft and Google: Authorization: Bearer <PROVIDER_ACCESS_TOKEN>. For Mercado Livre: https://www.address.com?access_token=<API-KEY>

OAuth Bearer Token

Uses an existing OAuth token and adds an authorization header: Authorization: Bearer <TOKEN>

NTLM

Handles NTLM authentication automatically using the credentials defined in the account.

To learn more about account types and configuration, read the Accounts documentation.

Using custom accounts

Custom Account #1 and Custom Account #2 allow you to reference account credentials directly in any field that supports Double Braces, except the URL field. This is useful when you need to use account values in a flexible way, without relying on the automatic authentication handled by the Account parameter.

Credentials referenced through custom accounts are not exposed in the connector output. The behavior is the same as other account types: values are used internally to perform the call and don’t appear in the pipeline response.

To use a custom account:

In the Authentication section, select the desired account in Custom Account #1 or Custom Account #2.
In any field that supports Double Braces, reference the account values using the expressions below.

The OAuth 2 account type is not supported for custom account references.

The available fields depend on the account type selected:

Account type

Available fields

API Key

{{ account.custom-1.url-param-name }}
{{ account.custom-1.value }}

Basic

{{ account.custom-1.username }}
{{ account.custom-1.password }}

Custom Auth Header

{{ account.custom-1.header-name }}
{{ account.custom-1.header-value }}

OAuth Bearer Token

{{ account.custom-1.token }}

Certificate Chain

{{ account.custom-1.chain }}
{{ account.custom-1.password }}

Google Key

{{ account.custom-1.key }}
{{ account.custom-1.scopes }}

AWS V4

{{ account.custom-1.service-name }}
{{ account.custom-1.access-key }}
{{ account.custom-1.secret-key }}
{{ account.custom-1.session-token }}
{{ account.custom-1.region }}

OAuth 2

{{ account.custom-1.provider }}
{{ account.custom-1.scopes }}

NTLM

{{ account.custom-1.username }}
{{ account.custom-1.password }}
{{ account.custom-1.domain }}
{{ account.custom-1.hostname }}

Replace custom-1 with custom-2 when referencing Custom Account #2.

Example: Using a Basic account to pass credentials in the request body:

{
    "username": "{{ account.custom-1.username }}",
    "password": "{{ account.custom-1.password }}"
}

PreviousEmail V1: Usage example (Deprecated)NextREST V1 (Deprecated)

Last updated 18 days ago

Was this helpful?

hashtagOverview

hashtagImporting from cURL or OpenAPI

hashtagParameters

hashtagConnection

hashtagAuthentication

hashtagTimeouts

hashtagError handling

hashtagResponse

hashtagAdvanced

hashtagDocumentation

hashtagMessages flow

hashtagInput

hashtagOutput

hashtagREST V2 in action

hashtagConfiguring the timeouts

hashtagConnect timeout

hashtagRead timeout

hashtagWrite timeout

hashtagCall timeout

hashtagSending a binary file

hashtagMaking requests with content-type: multipart/form-data

hashtagMaking requests with content-type: application/x-www-form-urlencoded

hashtagUsing accounts

hashtagUsing custom accounts

Overview

Importing from cURL or OpenAPI

Parameters

Connection

Authentication

Timeouts

Error handling

Response

Advanced

Documentation

Messages flow

Input

Output

REST V2 in action

Configuring the timeouts

Connect timeout

Read timeout

Write timeout

Call timeout

Sending a binary file

Making requests with content-type: multipart/form-data

Making requests with content-type: application/x-www-form-urlencoded

Using accounts

Using custom accounts