HTTP node

The HTTP request node is how a scenario talks to the outside world. Everything else on the canvas either gets data ready for it, or works with what it brought back.

Method

The method has to match what the other side expects. If you get it wrong, the request fails even though the URL is perfect, and that is the first thing worth checking when something does not work. Integrations often use different methods at different steps, so check each request on its own.

• GET asks for something. Parameters go in the URL and there is no body. You use it for status checks and validations.
• POST submits something new. The data goes in the body. This is how leads are sent.
• PUT replaces a whole record.
• PATCH changes only part of one.
• DELETE removes a record. With leads that usually means a cancellation.
• HEAD asks only for the headers. Handy when you just want to know whether the endpoint is alive.
• OPTIONS asks what the endpoint supports. You will rarely need it.

Endpoint

The URL the request goes to.

Rather than typing the full URL into every request, store the base as a parameter and write {endpoint}/register-lead. Then you have one place to change it when the advertiser moves their API, and you can point everything at a sandbox by swapping a single value.

If you put query parameters straight into the URL, they are kept. PalDock merges them with anything you add in the query list, so you can use whichever is more convenient.

Pingtree type

You only need this when the integration runs in a pingtree. It tells PalDock whether this request is the ping, the post, or the post verification.

Leave it empty and PalDock treats the flow as a post. That is fine while the integration has one flow. As soon as you want a second Start node on the canvas, both need a type, otherwise PalDock cannot tell which one to run.

Format

The format decides how the body is packaged. The other side accepts one and rejects everything else, so read their documentation instead of guessing.

• JSON sends an object in the body. Most modern APIs want this.
• form-data uses multipart encoding, typically for file uploads.
• x-www-form-urlencoded sends key=value pairs joined with &. Older APIs often want this.
• x-www-form-urlencoded + JSON is a hybrid: parameters are URL encoded, but a field can still carry JSON.
• login-pass-data sends credentials alongside the data, for APIs that do not use tokens.

This setting covers the whole request. Individual fields can still be nested inside it, and Field format explains how.

What goes in the request

Query parameters are added to the URL. They are usual for GET, but they work with any method.

Headers carry everything around the data: content type, authorisation, and whatever custom keys the API asks for.

Body is the payload itself, for POST, PUT and PATCH.

Every value is a plain text field. You type what you need and use the picker to drop in a reference, which shows up as a tag but is stored in braces, like {data_first_name}. You can mix the two, so Bearer {token} and {first_name} {last_name} both work.

PalDock adds User-Agent: CC/2.0 and Accept: application/json on its own. If you set either of them yourself, yours is used instead.

Empty and missing values

Some APIs care about the difference between an empty string, a null, and a field that is not there at all, and they will reject the request if they get the wrong one. Two settings handle it, and both apply to the query and the body.

Convert blank values changes the value before it goes out:

• empty string to null
• null to empty string
• missing to null
• missing to empty string
• empty string or missing to null
• null or missing to empty string

Skip field when drops the field from the request altogether:

• null
• empty string
• missing
• null or empty string
• missing or empty string
• null or missing
• null, missing or empty string

The difference is what actually arrives. Convert sends a different value, Skip sends nothing. When an API rejects a null but is perfectly happy if the field is not there, Skip is what you want.

Parser

The parser decides how the response is read.

Choose JSON or XML and PalDock turns the response into something you can address field by field, like {parsedBody.leadId}. Anything else is left as plain text, and {parsedBody} stays empty.

If you leave the parser alone, PalDock goes by the content type the other side declared. Set it yourself when they declare the wrong one, which happens more often than you would expect with older APIs that return JSON but label it as HTML.

Watch out for this one, because it fails quietly. The request goes through, the status is 200, and every condition reading {parsedBody.something} finds nothing at all. If your conditions behave as though the response were empty, look here first.

Insecure

PalDock normally checks the certificate of the server it is calling, and refuses to send anything if the certificate is expired, self signed, or belongs to a different host.

Turning on insecure skips that check. It is there for a partner’s test environment with a self signed certificate. On production it means you no longer know for certain who is receiving your lead data, so use it to get unblocked and then ask them to fix the certificate.

Timeout

The timeout is how long the request waits for an answer before giving up. It is a ceiling, not a delay, so if the answer comes back in half a second, the flow carries on in half a second.

Keep it short inside a Structure, because the customer is sitting in front of the form the whole time. There are also limits on the node, the run and the scenario above this one. See Limits and timeouts.

Authentication

There is no separate authentication node. Credentials go into the request like any other value, usually as a header.

A static token or API key is the easy case. Store it as a parameter and use it:

Authorization: Bearer {token}
X-Api-Key: {token}

Basic auth takes one more step, because the header carries a single encoded string rather than two values:

1. A Set node joins them, for example {auth0} = {client_id}:{client_secret}.
2. A Modify Field node runs to-base64 on it and writes the result into {auth}.
3. The header then reads Authorization: Basic {auth}.

A token you have to fetch, as with OAuth or JWT, needs its own request before the real one:

1. An HTTP node calls the token endpoint. These endpoints usually want x-www-form-urlencoded with grant_type in the body, and are themselves protected by Basic auth as above.
2. The connection leaving that node checks that a token actually came back, for example that {parsedBody.access_token} is not empty. Skip this and the flow carries on with an empty token, and every request after it fails for reasons that make no sense.
3. A Set node stores it as {token}.
4. Everything after that sends Authorization: Bearer {token}.

That auth call is a normal node, so it takes its own time and counts against the limits. If several requests in one flow would each fetch the same token, fetch it once at the start instead.

Signature

When the other side wants signed requests, use the Signature setting rather than building the signature by hand. PalDock covers MD5, HMAC, Digest and HTTP Signatures through presets. See Signature.

What you get back

Everything the request produced is available to the nodes after it:

• {status} is the HTTP status code.
• {parsedBody} is the parsed response, addressed with dots, as in {parsedBody.offers.0.offerId}.
• {body} is the raw response as text, whether it parsed or not.
• {headers} are the response headers.
• {uri} is the URL that was called.
• {query}, {request_body} and {request_headers} are what PalDock actually sent.

Those last three are the ones to reach for when a request is rejected and you cannot work out why. They show what really left PalDock, rather than what you meant to configure.

Before and after

Before the request, use Modify to get values into the shape the other side wants. Doing it there instead of inline means that when a value arrives wrong, you can see where it came from.

After the request, put conditions on the connections leaving the node to work out what the response means, and use Set to keep what you need, usually {external_id} and {redirect_url}.

Common mistakes

• The wrong method with the right URL.
• The wrong format with the right method and URL.
• Treating any 2xx as acceptance. Most rejections arrive with a perfectly normal status code.
• The wrong parser, so every condition reads an empty body and nothing ever matches.
• No check that the token request actually returned a token.
• The base URL typed into every request instead of stored as a parameter.