web.post

Sends a HTTP POST request to the specified URL.

web.post(url, headers, body, base64Body)

Parameters

• url (string): The URL to send the POST request to.
• headers (object): An object containing custom headers to include in the request. The keys represent header names, and the values represent the corresponding header values. (optional)
• body (object|string): The request body data. It can be an object representing key-value pairs (to be serialized as JSON) or a string with the raw body data. (optional)
• base64Body (boolean): A boolean flag indicating whether the response body should be returned as a base64-encoded string. Default value is false. (optional)

Returns

• response (object): An object representing the HTTP response containing the following properties:
  • status (number): The HTTP status code of the response.
  • headers (array): An array of header objects, where each object has one key/value pair representing a header.
  • body (string): The response body as a string or as a base64-encoded string if the content type is binary.
  • error (string): An error message if an exception occurred while sending the request.

Examples

var requestBody = { "name": "John Doe", "email": "john@example.com" };
var response = web.post("https://api.example.com/users", { "Content-Type": "application/json" }, requestBody);

// Check if the response status code is in the success range (between 200 and 299, inclusive).
if (response.status >= 200 && response.status < 300) {
    console.log("Request succeeded.");
    console.log(response.body);
} else if (response.error) {
    // An error occurred while sending the request (e.g., network error, timeout, etc.).
    console.log("Error occurred while sending the request: " + response.error);
} else {
    // The request failed with a non-success status code.
    console.log("Request failed with status code: " + response.status);
    console.log(response.body);
}

Notes

• The web methods automatically detect most common binary MIME types (e.g., images, PDFs, audio) and encodes the response in base64. However you should use the web.download method if your intention is to download files.

• If a request fails due to an error processing the request, an appropriate message is provided in the error field of the response, while the status field may remain 0.

TIP

Understanding Server Responses and Errors

• The status field reflects the HTTP status code returned by the server. A 4xx or 5xx status code typically indicates that the request was processed but resulted in an error on the server side. You can learn more about HTTP status codes here.

• The error field is only populated when the request fails before reaching the server or when no response is received. This may happen due to:

  • An invalid or malformed URL.
  • A client-side timeout while establishing the connection or waiting for a response.
  • Network failures such as loss of internet connection, DNS resolution issues, SSL validation errors, or blocked requests.
  • The server dropping or rejecting the request without responding.