Reference
Make a web request Data Action

Make a web request is an action node in Pendula that facilitates HTTP communication with external services during an experience. This article provides a comprehensive guide on configuring steps for authenticated web requests, employing methods like POST, GET, PUT, and PATCH.

What is a web request?

A web request is a bit like sending a detailed letter to an address, asking for specific information to be sent back, or to ask the recipient to perform an action, and then waiting for their response.

When you use the internet, HTTP (Hypertext Transfer Protocol) acts as a set of rules for transferring files (text, graphic images, sound, video, and other multimedia files) on the web. In the context of a Pendula flow, we can use HTTP requests (web requests) to perform tasks or get information.

In the context of Make a web request node, an authenticated web request refers to a request sent with credentials to confirm the requester’s identity. This authentication can be accomplished through various methods, such as username/password, request headers, or bearer tokens, ensuring secure access to protected resources. Pendula supports the following HTTP methods for web requests -

GET: Retrieves data from a specified resource. Use GET in Pendula to fetch information needed for your workflows, such as customer details from an external CRM system.

POST: Submits data to be processed to a specified resource. Use POST in Pendula to create new entries, such as registering a new user in a database.

PUT: Updates a specific resource completely through the replacement of its current state with the one provided in the request body. Use PUT in Pendula for comprehensive updates, like changing a complete user profile or updating an entire record.

PATCH: Applies partial modifications to a resource. Use PATCH in Pendula for making incremental updates, such as adjusting a single attribute of a customer record like an email address or phone number.

Usage scenario

Some examples of how Make a web request can be used include:

• Retrieving Data: You might send a web request to get data from a database. For example, if you're looking at customer demographics, your request would ask for this specific information from the specified service (for instance, a CRM).
• Sending Data: Similarly, you might need to send information, like updating customer records or posting content to social media. This involves sending a web request to the relevant service with the data you want to upload or modify.

The following example demonstrates a practical application of the Make a web request within a flow, illustrating how these messages are processed to ensure an effective feedback loop following a new purchase.

Configuring the action

Prerequisite for creating an authenticated web request

For authenticated web requests, ensure you securely store the necessary credentials from the external service within the Integrations page. These credentials will be essential for configuring the Make a web request node to authenticate and authorise the request for secure data exchange.

For a detailed guide on creating an authenticated web request credential, see Make a web request Authentication

Creating and configuring a web request

1. When building your flow, drag and drop the Make a web request node onto the canvas at the desired point where you want to make a web request.

2. In the Request details section, select the HTTP request method you want to use (GET , PUT , PATCH or POST ) The external service you are calling out to will inform you on what method is suitable.

3. Enter the API endpoint URL – this is the address where you want to send the request to.

   You can dynamically customise your request's URL with data from previous nodes in the flow by using merge fields directly into the URL parameters. This method allows the API endpoint to adapt based on context, effectively using real-time data to query specific information or actions relevant to the user.

   https://api.example.com/users?userid=userId&mobile=mobile
   

   In this configuration, userId and mobile are merge fields within the URL. They are dynamically replaced with actual values from previous nodes when the flow executes.

4. Under Authentication, specify if your request requires verification. Select 'Bearer', 'Username & Password', or 'Headers' for authenticated access.

   If the credential hasn't been added for authenticated access, you can add one in the Integrations page. See Make a web request Authentication

5. You can also add headers in the Request headers section, if necessary.

   For headers related to security, such as 'Authorization' , add these through your web request credentials in the Integrations page. This helps centralise security management and simplifies the configuration process.

Configuring the request body

In the Request body section, you can select content type (JSON by default) and configure the request body payload using the property builder.

1. In the Property field, type the name of the data attribute you want to include in your request (e.g., username, email).
2. Select the Type from the dropdown: string, boolean, or number, depending on the data you need to input.
3. In the Value field, input the actual data or select the merge field icon to dynamically insert data from previous nodes.

If you wish to build your own JSON payload using code, you can select the ellipses next to the property builder, and choose Convert to code. Note that this action is not reversible, and you'll need to Reset to get the property builder back.

If you wish to send an empty request body for PUT , PATCH or POST actions, you can select the ellipsis icon > Convert to code.

Advanced request preferences

• Follow Redirects: Allow requests to follow HTTP 3xx requests for a maximum of 10 redirects. This is useful for accessing requested resources that have moved to a new URL.

  • Retain the authorization header when a redirect happens to a different hostname.
  • Retain the original HTTP method after a redirect.

• Timeout: Wait for 100 seconds (configurable up to 360 seconds) for a response from the server before timing out. Adjust this setting if you require a longer or shorter wait time depending on the service you are interacting with.

These advanced settings ensure your web requests are handled efficiently and securely, providing greater control over how HTTP requests are processed within your workflows.

Outcomes

The "Outcomes" tab allows you to configure how the experience should continue after the "Make a Web Request" node.

• Success: The experience will continue on this path if the web request response is accepted with a 2xx status code.

Example of a Success Response:

{
"outcome": "success",
"outcomeReason": "ok",
"response": {
"cats": [ "cougar", "lion", "jaguar" ]
},
"code": 200
}

• Fail: The experience will end if the web request response encounters client errors (4xx), server errors (5xx), or unsupported formats. You can enable the "Path" option to handle failures within the flow.

Examples of Failure Responses:

Unsupported Format:

{
"outcome": "failure",
"outcomeReason": "request-failed",
"cause": "io.circe.ParsingFailure: expected json value got '<!doct...' (line 1, column 1)",
"message": "Outbound Webhook Failed: RawContentType[text/html] was not supported, and response could not be decoded as the fallback content type: JSON\n. Response[code=200, content-type: Some(text/html), body=Right(<!doctype html><html><body>Forests</body></html>)]. Request[method=GET, uri=http://localhost:20000/get-animals/html, content-type: None, body: NoBody]",
"code": 200
}

404 Not Found:

{
"outcome": "failure",
"outcomeReason": "request-failed",
"code": 404,
"cause": "Failed outbound request: Not found",
"message": "Outbound Webhook Failed: Request failed with non-successful status code: Response[404 Some(text/plain; charset=UTF-8)]\n. Response[code=404, content-type: Some(text/plain; charset=UTF-8), body=Left(Not found)]. Request[method=GET, uri=http://localhost:20000/not-existing-path, content-type: None, body: NoBody]"
}

Internal Server Error:

{
"outcome": "failure",
"outcomeReason": "request-failed",
"code": 500,
"cause": "Failed outbound request: ",
"message": "Outbound Webhook Failed: Request failed with non-successful status code: Response[500 None]\n. Response[code=500, content-type: None, body=Left()]. Request[method=GET, uri=http://localhost:20000/fail-call, content-type: None, body: NoBody]"
}

These outcomes ensure that your workflows can handle different scenarios appropriately, providing clear paths for success and failure conditions.

Use data from a web request response: Sample response

When using Make a web request, data is not only sent to an endpoint, but a response can also be received from the external service. The data from the response can be used in the flow by referencing merge fields in later nodes.

For a detailed guide on merge fields, see Working with merge fields

To view and use these merge fields, we need to provide the Make a web request node with a sample response.

By navigating to the 'Merge fields' tab on the Make a web request node, you will see the merge field explorer, 'This node' is selected, and the ability to paste a sample payload of the response:

The sample response must be in JSON format (key value pairs, objects, arrays). Here's an example of a response body, in JSON format:

{
"userid": "harrison-example",
"firstname": "harrison",
"lastname": "koenig",
"mobile": "+61400000000"
}

When you paste the sample response into the field, Pendula checks to make sure the data is correctly formatted, and highlights any errors that may need to be corrected, so you can be confident the data is valid before starting the flow.

Note that we currently only support one sample payload. If your responses can have different structures, you may need to manually enter the merge fields by typing.

Merge fields

You can reference any merge fields from nodes previous to this node. Learn more about merge fields

In later nodes, when viewing the available merge fields for the Make a web request node in merge field explorer you can expect to see: