HTTP request

Make an HTTP request to an external service.

• Kind: http
• Palette: Activities
• Run it on its own: yes

When to use

• Calling an API that no connector covers, or a connector action that doesn’t expose an option you need, such as a header or a request field.
• Posting to a webhook of your own.

For a service with a connector, its action is shorter: the connector already knows the URL, the auth shape and the body.

Configuration

Field	Type	Required	Description
url	string	yes	Request URL.
body	any	no	Request body (JSON or a string).
credential	string	no	Named credential injected as auth (header/bearer per the credential).
fail_on_error_status	boolean	no	Fail the node on any 4xx or 5xx. Shorthand for listing them in retry_on.
headers	object	no	Request headers, as a JSON object.
method	string	no	HTTP method (default GET).
optional_when_untrusted	boolean	no	Run without the credential when the run is untrusted (a fork pull request), instead of failing. The credential is still withheld.
retry_on	array	no	Status codes that fail the node instead of returning, so its retry: policy applies (e.g. [429, 503]).

Output

Field	Type	Description
status	integer	The HTTP status code.
headers	object	The response headers.
body	any	The response body, parsed as JSON when it is JSON.

Example

Fetch an order, and fail the step (so its retry: applies) when the API is overloaded:

version: hyperspool-graph/v1
nodes:
  - id: fetch
    type: http
    config:
      url: { $template: "https://api.example.com/v1/orders/{{ input.order_id }}" }
      credential: orders-api
      retry_on: [429, 503]
    retry: { attempts: 3, backoff: 10s }
  - id: report
    type: shell
    config:
      run: { $template: "echo order is {{ nodes.fetch.output.body.status }}" }
edges:
  - { from: fetch, to: report }

The credential is added to the request as it goes out; the graph and the run history carry only its name.

When a status fails the step

On an http step a response status is data. A 503 comes back as output.status with the body beside it, the step succeeds, and a step below reads nodes.fetch.output.status to decide what happens next. A retry: policy only fires on a failed step, so it never sees that 503. Two settings make a status fail the step instead:

• retry_on: [429, 503] fails on the codes you list.
• fail_on_error_status: true fails on any 4xx or 5xx.

Against a service that answers 503 twice and then 200, the fetch step above makes three requests and succeeds. A code you didn’t list stays data: retry_on: [429] in front of a 503 returns normally. A failed attempt’s error names the URL and the status and quotes the first 200 characters of the body, where the reason for a rejection usually is. continue_on_error: true absorbs the failure like any other.

A failed status is retried when asking again can change the answer: a 5xx, a 408 timeout, a 409 conflict or 423 lock that may clear, a 401 (the credential may have been refreshed since), a 425, a 429, and any 4xx that comes with a Retry-After header. Any other 4xx (a 400, a 403, a 404) fails the step at once, whatever retry: allows, since the same request gets the same answer. A code you list in retry_on is retried all the same.

Connector steps start the other way round, with fail_on_error_status on; see Connectors.

See the node reference for every other node.