HTTP Request

Edit online

The HTTP Request block is used to send HTTP requests to servers outside of the instance, allowing for data exchange between systems.

Procedure

To use the HTTP Request block in your workflow, complete these steps:

  1. Optional: Create an authentication that contains the credentials for the host where you want to send the HTTP Request.
    1. In the workflow editor, click Auth.
    2. In the dialog, in the Service field, select a generic authentication service, such as Common/Basic Auth.
    3. Click Create authentication.
    4. In the dialog, enter a name and, optionally, a description.
    5. Enter the basic authentication credentials, such as the HTTP protocol, host, username, and password.
    6. Click Create.
  2. Drag the HTTP Request block onto your chosen location in the workflow.
  3. Provide the request parameter values. Use the following table for reference.
    Note: The Method and Host values are mandatory. All other values are optional.
    Table 1. HTTP request parameters
    Parameter More information
    Method
    • Select GET to request data from a specified resource.
    • Select POST to create or update a resource.
    • Select PUT to update a specified resource.
    • Select PATCH to apply partial updates to a resource.
    • Select DELETE to delete a resource.
    Host Specify the server or IP address to send the request to.
    • You can use several different formats to specify a hostname, and you can also include the port number and query parameters, as shown in these examples:
      • https://mydomain.com
      • https://mydomain.com/443
      • mydomain.com/443
      • https://mydomain.com/443/firstname=John&lastname=Doe
    • If you do not specify the HTTP protocol in the Protocol parameter, you must specify it in this parameter.
    • If values are specified for any of the following parameters, those values take precedence over the relevant parts of the Host value:
      • Protocol
      • Port
      • Path
      • Query
    • If the Host value is empty and an authentication is provided in the authKey parameter, the host value is taken from the authentication.
    Protocol
    • Select the HTTP protocol (http or https) to use for the request.
    • If you do not specify the protocol in the Host parameter, you must specify it in this parameter.
    • If you specify a protocol in both the Host parameter and this parameter, the value in this parameter takes precedence.
    Port
    • Specify the TCP port to connect to on the target host. For the HTTP protocol, the default port is 80, For secure HTTP (https), the default port is 443.
    • If you specify a port in both the Host parameter and this parameter, the value in this parameter takes precedence.
    Path
    • Specify the path to the requested resource on the host and port. For example, in the following URL, on the example.com host at port 8080, the path is /resource_path: 
      http://example.com:8080/resource_path
    • If you specify a path in both the Host parameter and this parameter, the value in this parameter takes precedence.
    Query Specify parameter values to filter the data that is returned in the response to the request. You can specify the values in two ways:
    • In the list of values that you want to send, if the parameter names are unique, use a JSON-encoded key-value array. You can use hardcoded values or workflow variables, as shown in this example: 
      {
    "access_key": $my_access_key,
    "units": $my_units
}
    • If parameter names are repeated in your list of values, use a string that separates each key-value combination with an ampersand (&), as shown in this example: 
      "dog_breed=labrador&dog_breed=terrier&dog_breed=wolfhound"
      By default, the requested values for repeating parameter names are sent as an array. To disable this behavior, set the value of the repeatQueryParams parameter to true.

    If you specify query parameter values in both the Host parameter and this parameter, the values in this parameter take precedence.
    Headers Specify metadata about the request, such as the domain name of the target host, information about the client that makes the request, and the type of content type in the request body. Use an object containing key-value pairs, as shown in this example: 
    {
    "Host": "example.com",
    "Accept": "application/json",
    "Accept-Language": "en-US",
    "User-Agent": "Mozilla/5.0"
}
    Cookies Specify an array of objects, each object containing key-value pairs for each of the cookie names and values that you want to include in the request, as shown in this example: 
    [{
    key: "session_id",
    value: "abc123xyz456",
    path: "/0c8e4c5c-a73a-4864-b8e2-3bf7bc5b2af1",
    domain: "mysubdomain.mydomain.com"
}, {
    key: "my-cookie-value",
    value: "theme=dark&lang=en",
    path: "/0c8e4c5c-a73a-4864-b8e2-3bf7bc5b2af1",
    domain: "mysubdomain.mydomain.com",
    sameSite: "Lax"
}]
    followRedirect Specify how you want the request to be processed when a redirection is in place for the requested URL.
    • Set this parameter's value to true if you want the request to be processed by the website that you are redirected to.
    • Set the value to false if you want the request to be processed before you are redirected.
    rejectUnauthorized Set this Boolean value to true if you want to receive an error when the host's security certificate is invalid.
    Proxy Specify the URL of the proxy server. You can specify this URL without authentication credentials, for example, by using the format http://<host_name>:<port_number>, or with them, for example, by using the format http://<username>:<password>@<host_name>:<port_number>.
    Body For requests that use the POST, PUT, and PATCH methods, specify the data that you want to send to the host. For example, you might send these three key-value pairs in a JSON array: 
    {
    "first_name": "John",
    "last_name": "Doe",
    "age": 25
}
    bodyEncoding

    Select binary from this drop-down if you want to send binary data as a buffer inside the message body.

    By default, the format of the message body is determined automatically.
    attachments Specify an array of objects that represent the files that you want to attach to the request.
    • Each object contains one file.
    • If you attach files, make sure that in the header parameter, you set the Content-Type key's value to multipart/form-data.
    authKey
    • Select the authentication that you specified in step 1, or specify authentication credentials for the target host.
    • If you select an authentication, its host is overridden by the value in the request's Host parameter.
    responseEncoding Specify the text encoding that is used for the response. You can select binary or utf-8 encoding.
    timeout Specify a value in seconds that applies to the following two timeouts:
    Response timeout
    If the host does not respond to the request within the time that you specify, the request is aborted.
    Connection timeout
    If no connection is made to the host within the timeout period, the HTTP socket times out.
    insecureConnect Set this Boolean value to true if you want to allow a connection to be made with older hosts that do not support modern security standards, for example, because they require legacy SSL or TLS renegotiation methods. By default, this value is set to false.
    Note: Setting this value to true reduces the security of your connections. Take this step only when necessary and ensure that you understand the security implications.
    async Set this Boolean value to true if you do not want your workflow to wait for the response to the request. If you set this parameter to true, the value of this block's result variable is set to HttpRequest was sent when you run the workflow.
    enableTimings Set this Boolean value to true if you want this block to provide timing details for events that happen during the request and response.
    • These timing details include the time that the request was made, the time that an HTTP socket was assigned to the request, the time that the DNS lookup finished, and so on.
    • The timing details are returned in the timings and timingPhases block variables.
    Note: If you set this value to true, the block's behavior might be affected. For example, redirects that are configured for the server might not be followed.
    repeatQueryParams Set this value to true if you do not want to use an array to send values for repeating parameters in the Query parameter.
  4. Use an Assign block to assign the HTTP response body to a workflow variable, such as $result.
  5. Click Run. Verify that the request was submitted successfully and that the response is shown in the workflow logs.

Disabling the HTTP Request block

To temporarily disable the HTTP Request block, turn off the switch in the block header.