HTTP Request

The HTTP Request action lets you call any HTTP endpoint from a workflow. Configure method, URL, body/query params, headers, authentication, retries, and timeouts.

Method

• GET
• POST
• PUT
• PATCH
• DELETE
• HEAD
• OPTIONS

This is the “type” of request you’re making:

• Use GET when you want to retrieve data (for example, get a list of products).
• Use POST when you want to create something (for example, create an order).
• Use PUT or PATCH when you want to update something.
• Use DELETE when you want to remove something.

URL

This is the full address of the API endpoint you want to call.

• It’s required.
• You can bind it (for example, from a variable or an environment value).

URL params

Some APIs expect values inside the URL, like an ID:

Example URL: https://api.example.com/users/:id

When your URL contains /:something, WeWeb shows a URL Params section where you can fill in id.

Data

Query parameters

Use Query Parameters to add key/value pairs to the end of the URL.

• Example: { "search": "boots", "page": 1 }
• The final URL becomes something like: ...?search=boots&page=1

This is commonly used for searching, filtering, sorting, and paging.

Body

Use Body to send data to the API (for example, the details of a new order).

• This is usually used with POST, PUT, or PATCH.
• By default, the body is sent as JSON (which is what most APIs expect).

Authentication (optional)

Authentication is how you prove to the API that your request is allowed.

Credentials (cookies)

If the API uses cookies (common when you’re calling your own domain), Credentials controls whether the browser includes those cookies.

• Same Origin: Only send cookies to your own domain (this is the default).
• Include: Always send cookies (only use this when you understand why it’s needed).
• Omit: Never send cookies.

Auth type

In Auth, choose one of these:

• None: The API is public or doesn’t require sign-in.
• Basic: You send a username + password (less common for modern APIs).
• Bearer: You send a token (very common). This usually looks like Bearer <token>.

USE ENVIRONMENT VARIABLES FOR AUTH

If you’re using tokens or passwords, store them in environment values (or another secure place) and bind them. Don’t hardcode them.

What to fill

• For Basic, fill Username and Password.
• For Bearer, fill Token.

Headers (optional)

Headers are extra settings you send with the request. Many APIs use headers for authentication and for telling the API what format you’re sending.

Add custom headers as an object, for example:

{
  "Content-Type": "application/json",
  "X-Api-Key": "{{env.API_KEY}}"
}

Retry configuration (optional)

Retries are helpful when an API sometimes fails temporarily (for example, a short network issue).

• Max Attempts: How many extra tries to do after the first try. Use 0 to disable retries.
• Retry Type:
  • Linear: Wait the same amount each time.
  • Exponential: Wait longer and longer each time (useful when an API is rate-limiting you).
• Delay (ms): How long to wait between tries (for Linear).
• Base Delay (ms) And Max Delay (ms): How the wait time grows (for Exponential).

Use retries for flaky networks or 429/5xx responses. Avoid retrying actions that could create duplicates (for example “create order”) unless the API explicitly says it’s safe to retry.

Advanced options

Throw on Error

When this is enabled, WeWeb treats non‑success responses (for example 401 or 500) as an error. This makes it easier to handle problems in the workflow’s error branch (or with Try/Catch).

Timeout (ms)

This is the maximum time WeWeb will wait before it stops the request.

If you set it too low, slow APIs may fail. If you set it too high, your workflow may feel slow when the API is down.

THESE NEXT OPTIONS ONLY APPEAR IN INTERFACE WORKFLOWS

Keep Alive, Request Mode, Cache Mode and Priority are handled by the visitor’s browser, so they only show up when the action runs in the interface. They aren’t available when the action runs inside an API endpoint.

Keep Alive

This is off by default. When you turn it on, the browser is allowed to finish sending the request even if the visitor closes the tab or moves to another site.

It’s useful for last-moment calls, like recording that someone abandoned a checkout. Leave it off the rest of the time: browsers limit how much data you can send this way (roughly 64 KB), and a normal request already finishes on its own.

Request Mode

This tells the browser what kind of call it’s allowed to make. The default, CORS, is what you want almost every time.

• CORS: Call an API on another domain, as long as that API allows your app. This is the default.
• No CORS: The call goes out, but you can’t read anything back. Rarely useful.
• Same Origin: Only allow calls to your own domain. The request fails if the URL points anywhere else.
• Navigate: Reserved for page navigation. You won’t need it here.

CHANGING THIS USUALLY BREAKS THE CALL

If an API call stops returning data after you touch this setting, set it back to CORS. The other values restrict what the browser is willing to do for you, they don’t unlock anything extra.

Cache Mode

Browsers keep a copy of some answers so the same call doesn’t have to travel to the API twice. Cache Mode decides how much WeWeb relies on that stored copy.

The default, Default, suits almost every case: the browser reuses a stored answer while it’s still considered fresh, and asks the API again once it isn’t.

• Default: Reuse the stored answer while it’s still fresh, otherwise ask the API. This is the default.
• No Store: Never look at the stored copy, and never keep the answer. Use it for anything sensitive or constantly changing.
• Reload: Always ask the API, but keep the fresh answer for later calls.
• No Cache: Always check with the API before reusing a stored copy, so you get an up-to-date answer while still saving time when nothing changed.
• Force Cache: Reuse the stored copy even if it’s considered out of date, and only ask the API when there’s nothing stored at all.
• Only If Cached: Reuse the stored copy or fail. The API is never called.

You’d reach for No Store or No Cache on data that has to be current, like an account balance or the number of seats left. Force Cache suits data that barely changes, like a list of countries, where loading speed matters more than freshness.

ONLY IF CACHED NEEDS A MATCHING REQUEST MODE

Browsers only accept Only If Cached when Request Mode is set to Same Origin. With the default CORS, the request fails straight away. Change both settings together, or leave Only If Cached alone.

Two things to keep in mind. This setting only changes anything for GET calls, because browsers don’t store the answers to POST, PUT, PATCH or DELETE. And the API always has the last word: if it replies that its answer must not be stored, Force Cache has nothing to reuse and the browser calls it anyway.

Priority

When several calls start at the same time, this tells the browser which ones matter most.

• Auto: Let the browser decide. This is the default.
• High: Ask for this call to be handled before the others, for example the data your first screen needs.
• Low: Let this call wait, for example background tracking.

This is a hint, not a guarantee. Browsers are free to ignore it.

Result shape

On success, the action returns an object similar to:

{
  "status": 200,
  "headers": { "...": "..." },
  "data": { /* parsed JSON or text */ }
}

In later actions, you’ll usually bind:

• result.data For the returned data, or
• result.status If you need to check whether it worked.

Examples

GET with query params

1. Method: GET
2. URL: https://api.example.com/search
3. Query Parameters: bind { q: variables.search, limit: 20 }

POST JSON with Bearer token

1. Method: POST
2. URL: https://api.example.com/orders
3. Body: bind { items: variables.cartItems, customerId: variables.user.id }
4. Auth: Bearer → Token: bind variables.apiToken

Handle errors

Turn Throw on Error On and add logic in the error branch (e.g., show a toast, log, or set a variable).