Make a web request Data Action – Engagement Console

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

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.
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.
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.

When using the Make a Web Request action, Pendula automatically encodes URLs based on standard percent-encoding rules. In some cases, APIs that do not follow the URL encoding standard cannot be used with the Make a Web Request action.
If your API requires a specific encoding format and you're seeing unexpected behaviour, please reach out to our support team with details.
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
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.

In the Property field, type the name of the data attribute you want to include in your request (e.g., username, email).
Select the Type from the dropdown: string, boolean, or number, depending on the data you need to input.
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.

Handling errors and retries in web requests

When using the Make a Web Request action, Pendula does not automatically retry requests for operations that modify data, such as PUT or POST requests. This is to prevent unintended duplicate actions in external systems—for example, avoiding multiple record creations if an API returns an error after partially processing a request.

If a request fails, the experience will follow the configured outcome path, allowing you to handle errors within your workflow. If you need to retry a request, you can design your flow to detect specific response codes (such as 500 Internal Server Error) and perform another web request action, or your preferred logic.

Since every external system behaves differently, we recommend reviewing how your target API handles errors and deciding whether retries are appropriate for your use case.

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

This example shows a successful response from the OpenAI API, where the model returns a generated response with a 2xx status code.

outcome: success
outcomeReason: ok
response:
- id: "chatcmpl-7Gk2BjG2D4R9U" (unique identifier for the response)
- object: "chat.completion"
- created: 1684176874
- choices:
  - text: "The weather is nice in San Francisco."
  - index: 0
  - logprobs: null
- model: "gpt-4"
code: 200

Each example below simulates an unsuccessful API call to OpenAI, such as when the request has an unsupported format, or when a 404 or 500 error occurs. You can enable the "Path" option to handle failures within the flow.

Unsupported Format

This could occur if the API receives a non-JSON input or incorrect headers.

outcome: failure
outcomeReason: request-failed
cause: "io.circe.ParsingFailure: expected JSON value, got '<!doctype...' (line 1, column 1)"
message: "Outbound Webhook Failed: RawContentType[text/html] was not supported, and response could not be decoded as JSON\n. Response[code=200, content-type: Some(text/html), body=Right(<!doctype html><html><body>Error</body></html>)]"
code: 200

404 Not Found

This example shows a 404 error, which might happen if the request tries to access a non-existent endpoint.

outcome: failure
outcomeReason: request-failed
code: 404
cause: "Failed outbound request: Not found"
message: "Outbound Webhook Failed: Request failed with non-successful status code"

Internal Server Error

A 500 error example where the OpenAI API has a server-side issue.

outcome: failure
outcomeReason: request-failed
code: 500
cause: "Failed outbound request:"
message: "Outbound Webhook Failed: Request failed with non-successful status code"

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"
}

Note that any sample properties with 'null' values can't have a type, and sample value, inferred from them. Please only provide sample properties with not-null values.

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:

response	The body of the response		This object contains the body of the response from the server. To view these fields, you must copy the response body of the payload from the external service (not including headers) and paste into the Payload sample field.
code	The HTTP response status code	`200`	This is the code returned from the server.
outcome	The final request status (string)	`success`	The request was sent, and the response was understood.
outcome	The final request status (string)	`failure`	The request either failed to be sent, or the response failed to be decoded.
outcomeReason	The reason for the request status (string)	`ok`	This means that the request was successful, and its response was successfully decoded. Because the response might be plain text or JSON, it is stored in the response object.
		`invalid-request`	Pendula did not attempt to send the request, because some information about its configuration was invalid. This can include bad URLs, credentials not found, wrong types of arguments etc.
		`request-failed`	The request was sent, but it did not work. This could include situations where the response’s content-type wasn’t supported; meaning this can occur for a 200 response.