InvokeHTTP

InvokeHTTP is Clockspring’s processor for calling HTTP and HTTPS endpoints. Most teams use it to call APIs, but it can also download files or retrieve any content exposed over HTTP/S.

This article focuses on the settings that matter in real flows: authentication, headers, handling common errors, and troubleshooting.

Common Settings You’ll Use

HTTP Method

Choose the method required by the API (GET, POST, PUT, PATCH, DELETE). If you’re unsure, check the API documentation.

HTTP URL

This is the endpoint InvokeHTTP calls.

Best practice: use an attribute instead of hardcoding the URL when you expect it to change (pagination, cursor-based APIs, retries, multiple environments).

Example:

• HTTP URL: ${url}

Authentication Options

InvokeHTTP includes built-in authentication modes so you don’t have to manually build certain headers.

None

Uses no authentication. This is common for public APIs or internal endpoints protected by network controls.

Basic Authentication

When selected, two new properties appear:

• Username

• Password

Use this when the API expects standard HTTP Basic Auth and you want Clockspring to handle the header formatting for you.

Bearer Token

When selected, a new property appears:

• Bearer Token

Use this when the API expects an Authorization: Bearer <token> header. You do not need to create a dynamic header for Authorization when using this mode.

OAuth1 / OAuth2

OAuth modes point to Controller Services. This is the right pattern when tokens are obtained and refreshed automatically.

Tip: OAuth is usually the right choice when a token expires and must be refreshed without manual updates.

Custom HTTP Headers

Many APIs require headers beyond authentication (API keys, Accept headers, version headers, custom tenant IDs, etc.).

To add headers:

1. Open InvokeHTTP > Properties

2. Select the plus (+) icon

3. Add a dynamic property where:

   • The property name is the header name (example: API-KEY)

   • The value is either a literal or an attribute reference (example: ${my_api_key})

Use attributes for keys and tokens so you’re not hardcoding secrets into flows.

Custom Status Code Routes

InvokeHTTP can create custom relationships based on HTTP response codes.

What it does

In Custom Status Code Routes, enter one or more status codes (example: 429). Clockspring will create a new relationship for that response code, letting you route that specific condition differently than generic failures.

Why this matters

This is ideal for rate limits and “expected” errors where you want a controlled path.

Example use cases:

• 429 Too Many Requests: route to a pacing path, delay, or alternate schedule strategy

• 404 Not Found: route to a “missing record” path instead of treating it like a system failure

• 409 Conflict: route to conflict handling logic

This is usually cleaner than trying to infer the status code later or mixing retry behavior with business logic.

Timeouts and SSL

Socket Connect Timeout / Socket Read Timeout

These control how long InvokeHTTP waits:

• Connect timeout: time to establish the connection

• Read timeout: time waiting for the response after connecting

Adjust these when an API is slow or when you want failures to happen quickly rather than tying up threads.

Strict SSL Validation

If you connect to an endpoint with a self-signed or untrusted certificate, Strict SSL Validation may block the call. Turning it off can help in internal enterprise environments, but it reduces certificate trust checking.

SSL Context Service

Use an SSL Context Service when you need trusted certs, client certificates, or controlled TLS behavior.

Troubleshooting Checklist

When something fails, check these in order:

1. Status code

   • Is it 401/403 (auth)?

   • 404 (bad endpoint)?

   • 429 (rate limit)?

   • 5xx (server side)?

2. URL

   • If you’re using ${url}, inspect the FlowFile attributes to confirm the value is what you expect.

3. Headers

   • Confirm required headers are present and spelled correctly.

   • If using Bearer Token auth mode, don’t also set Authorization manually unless you mean to override it.

4. Response content type

   • If downstream processors can’t parse the response correctly, setting Override Response Content-Type to application/json often resolves it.

Related How-Tos

• API pagination loops (using ${url} and extracting the next page)

• Rate limiting patterns (429 handling without hammering retries)

• Content-type quirks (why mime.type and override content-type matter)