How to integrate anything

This page is the practical route from an advertiser’s API documentation to a working integration. The Editor explains the tool. This explains the method.

Before you start

Have these ready:

• The endpoint and the HTTP method.
• How the request authenticates: a token, a header, a signature.
• Which fields are required, and in what format.
• Check whether the advertiser restricts access by IP address. If so, provide them with the PalDock outgoing IP address below. However, we highly discourage relying on IP whitelisting, as it is an outdated approach that tends to cause more problems than benefits.
  • 159.69.100.31
  • 159.69.101.229
• What a successful response looks like, and what a rejection looks like.
• Test credentials, so you can send real requests without creating real leads.

If any of these are missing, get them first. Most integrations that take a long time to build are missing one of them.

1. Create the integration

Integrations live in the Integrations section. Click Add and either start from scratch or pick a ready-made one from the Library of Integrations. If the advertiser is already in the library and you use global fields, you may be finished in one click.

2. Add the Start node

Every scenario begins with a Start node. Choose the type that matches what the scenario is for: Integration, Structure or Tracking. See Where Connection Creator is used.

3. Put the data into the right shape

Advertisers rarely accept your data as it is. Phone numbers need a prefix stripped, dates need a different format, a country needs to become a code.

Use a Modify node for this, not the HTTP node. Keeping the transformation separate makes it obvious later where a wrong value came from.

4. Send the request

Add an HTTP node and fill in the method, the URL, the headers and the body. Values from the lead go in curly braces, for example {email}.

Two settings on this node matter:

• Timeout, how long to wait for the answer. If a visitor is waiting on a loading screen, keep it low.
• Signature, if the advertiser requires the request to be signed.

For nested payloads, see Field format.

5. Read the response

An answer of 200 OK does not mean the lead was accepted. Most advertisers return a rejection inside the body with a perfectly normal status code, so read the body, not just the code.

Store what you need with a Set node. The values worth storing almost every time:

• The advertiser’s own ID for the lead, into {external_id}. Without it you cannot match a later postback to this lead.
• The redirect URL, into {redirect_url}, if the visitor is sent onwards.
• The price, if the advertiser returns one.

6. Decide what counts as success

Put a condition on the connection leaving the HTTP node, so only an accepted lead continues down the success path. Everything else goes down the other path.

Be specific about what success means. Matching on a status code alone is the most common reason an integration reports accepted leads that the advertiser never received.

7. Finish the flow

End the flow so PalDock knows the outcome. A rejection is a valid outcome, not an error, and it belongs in the reporting the same as an acceptance. See Reject reason and Refuse leads.

PING and POST in a pingtree

When an integration is used in a pingtree, it can have more than one Start node, because each flow has its own separate path.

• The PING flow has its own Start and its own End.
• The POST flow has its own Start and its own End.
• Never connect PING and POST directly. The two flows must stay separate, with no connection between them.

Waiting, repeating and verifying

Some advertisers do not answer immediately.

• Add a Wait node to pause before you ask again. Remember that the visitor stays on the loading screen while this happens, so watch the synchronous limit.
• There is no node that retries on its own. You build the loop: an HTTP node asks for the status, and a connection leads back to the Wait for as long as the answer is not final.
• Always put a Breaker in that loop. It caps how many times the flow may go round, so a lead the advertiser never decides on ends cleanly instead of failing on a system limit.
• If the lead has to be verified, that is usually a second HTTP request after the first one succeeds.

If the advertiser calls you back instead of answering, use a Webhook node, which can wait far longer because nothing is blocked while it does.

Saving values from responses

You can store a value returned by a request and use it later in the flow, or after it.

• Predefined variables are listed in Tracking parameters.
• For your own variable, save it to a parameter with the prefix custom_ and reference it as {custom_anything}.

Stored values are kept in the database, so they remain available to tracking and postbacks long after the run has finished.

Test it before you go live

Send a test lead and open the run in the log. Go node by node and check what each one received and returned. Test a rejection too, not only an acceptance, because that is the path that usually breaks silently.

Common mistakes

• Treating 200 OK as acceptance.
• Not storing {external_id}, so postbacks cannot be matched later.
• Not storing {redirect_url}, so customers cannot be redirected to advertiser.
• Connecting PING and POST.
• A timeout so long that the visitor gives up before the flow finishes.