Send web request Action

This page describes the “Send web request” action. To start a workflow with a web request, use the “Web request received” trigger.

The “Send web request” action can be used to send a web request to an external server. This could be your own endpoint or the endpoint of another service accepting web requests.

Configuring the app

Credentials for outbound requests are configured once on the Primer Web Requests app, not on each action. When you connect the app you can set:

Setting	Description
Authorization Header	The credential sent with every request made by the “Send web request” action. By default it is sent as the `Authorization` header. Leave it empty if your endpoint does not require authentication.
Custom Authorization Header Name	Overrides the name of the header the credential is sent as, for example `X-API-Key`. If left empty, `Authorization` is used.
Incoming Authorization Token	Only used by the “Web request received” trigger to authenticate requests sent to your webhook URL.

Keep credentials on the app rather than in a custom header: values on the app are stored with the app connection, whereas custom header values are part of the workflow definition and visible to anyone who can edit the workflow. Connect the app once per set of credentials; you can connect it several times if different workflows need different credentials.

Restrictions

The action currently has the following restrictions:

requests are synchronous: the workflow waits for the response before continuing
only https endpoints are supported
only GET and POST methods are supported
only JSON and form URL encoded (application/x-www-form-urlencoded) request bodies are supported. A JSON payload must be a JSON object
custom headers are supported, except for a set of blocked headers that are dropped from the request
requests to private or internal network addresses, localhost, and any primer.io domain are rejected
the request is sent exactly once; failed requests are not retried
the response body is only available to later blocks if it is a JSON object

If you have different requirements for your particular automation, please reach out to us directly via our Support Portal to tell us more about your request. If you don’t have access, please contact your account administrator for assistance.

Sending the request

Configure the following inputs to set up the action:

Input	Description
Target URL	The external server to send the request to. Only https endpoints are supported. The hostname must resolve to a public IP address; see URL validation.
Method	`POST` (default) or `GET`. No payload is sent for `GET` requests.
Body format	`JSON` (default) or `Form URL encoded`. Only available for `POST` requests.
JSON payload	Shown when Body format is `JSON`. The JSON payload for `POST` requests. It must be a JSON object. There is only partial validation available when a proper JSON payload is constructed, as the values are replaced only during runtime of the workflow. If the payload is not valid JSON at runtime, the request is not sent and the action fails. Use the Workflow Runs to debug the actual request passed and response received in case of problems.
Form fields	Shown when Body format is `Form URL encoded`. One entry per field, each with a name and a value. Values can use variables from earlier blocks. See Sending a form URL encoded body.
Custom Headers	Additional headers to send as `name`/`value` pairs. These can override the default `Content-Type` and `User-Agent` headers. Blocked headers are dropped. Do not use this for API keys or other credentials; set those on the app instead (see Configuring the app).
Fail action on unsuccessful request	Boolean (default: True). Determines how the workflow handles failed web requests. When True, the workflow stops on failure; when False, it continues execution even if the request fails. See Failure handling.

Example JSON request with a placeholder for some variables. Use the variable selector to assign outputs from different blocks when creating this request.

JSON

{
  "customRequestType": "RECOMMENDATION_ENGINE",
  "paymentId": "[PAYMENT_ID]",
  "orderId": "[ORDER_ID]",
  "customerId": "[CUSTOMER_ID]",
  "ruleDescription": "Get recommendation on how to proceed after a payment was created."
}

Sending a form URL encoded body

Some APIs expect application/x-www-form-urlencoded instead of JSON. Set Body format to Form URL encoded and add one entry per field under Form fields. Brackets in field names are kept, so you can build nested values, for example items[0][price]. Names and values are URL encoded when the request is sent. For example, these fields:

Name	Value
`amount`	`1000`
`expand[]`	`customer`
`expand[]`	`latest_charge`

are sent as:

Request body

amount=1000&expand%5B%5D=customer&expand%5B%5D=latest_charge

The following rules apply to form fields:

a field with an empty name is skipped
a field with an empty value is sent as name=
the same name can appear more than once, for example expand[]. Fields are sent in the order of the list

Headers sent with the request

Every request includes the following headers unless noted otherwise. Header names are case-insensitive, so a custom header with the same name as a default replaces it.

Header	Value	Notes
`Content-Type`	`application/json`, or `application/x-www-form-urlencoded` when Body format is `Form URL encoded`	Can be overridden with a custom header. The body is not converted to match.
`User-Agent`	`Primer Web Request App`	Can be overridden with a custom header.
`Authorization`	The Authorization Header value set on the app	Only sent if a value is configured on the app. The header name follows Custom Authorization Header Name when set. The app value takes precedence over a custom header with the same name.
`Referer`	`primer.io`	Always sent and cannot be overridden. It identifies requests coming from Primer and lets the trigger reject requests sent back to Primer.

Tracing headers used internally by Primer are not forwarded to your endpoint.

Blocked headers

For security reasons, some headers cannot be set through Custom Headers. If a blocked header is configured, it is dropped and the request is still sent. The Workflow Run shows a message listing the headers that were dropped:

Workflow Run message

The following headers were configured on the workflow, but are not supported: host, x-forwarded-for

The following headers are blocked (case-insensitive):

Category	Headers
Host and routing	`Host`, `X-Original-URL`, `X-Rewrite-URL`
HTTP protocol control	`Content-Length`, `Transfer-Encoding`, `Connection`, `Upgrade`, `Expect`
Client IP and proxy identity	`X-Forwarded-For`, `X-Forwarded-Host`, `X-Forwarded-Proto`, `X-Real-IP`, `X-Client-IP`, `X-Original-IP`, `Forwarded`, `Via`
Request origin	`Origin`, `Referer`
Proxy authentication	`Proxy-Authorization`, `Proxy-Authenticate`, `Proxy-Connection`
Primer internal	`X-Primer-Branch`, `X-Primer-Context`, `X-Primer-Flags`, `X-Primer-Timeout-Policy`
CDN	Any header starting with `CloudFront-`

URL validation

The Target URL is validated before the request is sent. The action fails without sending anything if:

the URL does not use the https scheme
the host is localhost, a private or internal IP address (such as 10.x.x.x, 172.16.x.x to 172.31.x.x, 192.168.x.x, 127.x.x.x, link-local or other reserved ranges, or their IPv6 equivalents), or a hostname that resolves to one of these addresses
the hostname cannot be resolved
the host is primer.io or any subdomain of it. This prevents workflows from calling Primer and starting themselves again in a loop.

The error shown in the Workflow Run lists the specific issue, for example Invalid URL, scheme not allowed: http.

Handling the response

The following response data is available in the output of the action:

Output	Description
Response Body	The payload, available as “unstructured data” if the response is a JSON object. If the response is not JSON, or is a JSON array or scalar, this is empty.
Response content-type	The content type of the response (e.g., `application/json`).
Response status	The HTTP status code of the response.
Success	Boolean indicating whether the request was successful (`2xx` status).

You can pass this data to another workflow block using the variable selector. For the Response Body, you must specify the path to the variable you want to use.

It is also possible to use that data to build conditions in the same way.

The full request and response, including headers, are shown in the Request & response tab of the Workflow Run. Values of credential headers such as Authorization, Cookie, or headers whose names end in -Key, -Token, -Auth or -Secret are masked there.

Timeouts

Phase	Limit	Description
Connecting	5 seconds	Time allowed to resolve the hostname and open a TCP connection, and then again for the TLS handshake. An endpoint that does not accept connections fails within roughly 10 seconds.
Waiting for a response	60 seconds	Time allowed for the server to start responding and for each subsequent read of the response. A connected endpoint that never responds fails after 60 seconds.

The request is sent exactly once. If it times out or fails, it is not retried, so your endpoint will not receive duplicate requests from a single action execution. If you need retries, add them to your workflow explicitly or handle them on your side.

Keep your endpoint’s response time well below the limits above. When this action runs as part of a payment flow, for example before authorizing a payment, the checkout waits for the workflow to finish and a slow endpoint delays the payment result for your customer.

If a use case requires a longer duration, then this synchronous action is not the right approach. Consider splitting the request and using the “Web request received” trigger to continue.

Failure handling

A request is treated as unsuccessful when:

the Target URL fails validation or, when Body format is JSON, the JSON payload is not valid JSON
the connection fails or times out, or the server does not respond in time
the server responds with a status code outside the 2xx range

By default, an unsuccessful request marks the workflow run as and no further blocks are executed. The Workflow Run shows the reason, for example Unexpected http response code [503] from https://example.com/recommend. Set Fail action on unsuccessful request to False to let the workflow continue instead. The action then completes with Success set to false. When a response was received, Response status, Response content-type and Response Body are still populated so you can branch on them. When no response was received, for example on a timeout or an invalid URL, only Success is set and the Workflow Run shows a message explaining why, such as the target server took too long to respond.

Learn more about debugging workflow runs.

Example flow

An example use of the send web request action could be to use an internal recommendation engine before authorizing a payment. If the response contains a “recommendation” field with a value “PROCEED”, then the payment flow continues, otherwise the payment gets declined.

Start automating

Now that you know what can be achieved with this action, start creating a workflow.
Debug received requests or requests sent within the Workflow Runs

​Configuring the app

​Restrictions

​Sending the request

​Sending a form URL encoded body

​Headers sent with the request

​Blocked headers

​URL validation

​Handling the response

​Timeouts

​Failure handling

​Example flow

​Start automating

Configuring the app

Restrictions

Sending the request

Sending a form URL encoded body

Headers sent with the request

Blocked headers

URL validation

Handling the response

Timeouts

Failure handling

Example flow

Start automating