Webhook

A Webhook node pauses the flow and waits for an external system to call you. You need it when an advertiser accepts the lead but cannot say straight away what happened to it. Instead of asking them again and again, you give them a URL and they call it once they know. That is usually faster and always cheaper than polling.

Two ways to wait

The setting Pingtree waits until webhook finishes decides how the pause works, and the difference matters more than it looks.

• Switched on, the flow holds the line open. The pingtree stops and waits, the customer sits on the loading screen, and as soon as the call arrives the flow carries on with the data. Because something is genuinely blocked the whole time, the timeout here is capped at about 40 seconds.

Use it only when you are confident the advertiser answers within seconds. If they do not, you have held up the sale for nothing.

• Switched off, the flow is put down instead. Nothing is blocked, the pingtree moves on, and the run is picked up again when the call arrives. The wait can be as long as 48 hours.

This is the right choice for anything the advertiser has to think about, and for anything a human on their side is involved in.

What happens when nobody calls

The two modes behave differently here as well, which is worth knowing before you pick one.

• Waiting on the line, a timeout is an error. The run stops and the log says the webhook timed out after so many seconds.

• Released, a timeout is not an error. The flow simply carries on when the time is up, with none of the data it was hoping for. Put a condition on the connection leaving the node to check whether anything actually arrived, otherwise the flow continues as though it had an answer.

Webhook ID

Each webhook needs its own ID, and it forms part of the URL you hand to the advertiser. Keep a note of it. If you delete the webhook and build it again later, you can reuse the old ID so the advertiser never has to change anything on their side.

Endpoint

The URL the advertiser calls. Give it to them together with whatever identifier they should send back.

How the call finds the right lead

An incoming call has to be matched to the exact run that is waiting for it, and PalDock uses the same two methods as everywhere else in tracking. See Tracking processing.

• By the PalDock conversion ID. This is the identifier PalDock generated for the lead, and it is unique across the system, so on its own it is enough. Send it to the advertiser when you submit the lead and ask them to return it.
• By the advertiser’s external ID. Their own identifier for the lead, which is unique only in combination with the advertiser ID. This is why you store {external_id} from the response when the lead is submitted. See Set node.

If the call matches nothing, the advertiser gets back:

{"code":404,"message":"Waiting Webhook not found for provided token and identifiers"}

That response means one of three things:

• the run already timed out and stopped waiting,
• the identifier they sent is not the one you stored,
• or they called the wrong webhook.

When the advertiser uses different parameter names

Advertisers rarely call these identifiers what you call them. One sends lead_id, another sends operationId, and PalDock does not recognise either.

You do not have to accept their naming. In your workspace settings, under Custom ID parameter names in integrations, you list the names they use, and PalDock treats those as the identifier. There are three fields, one for the PalDock conversion ID, one for the advertiser ID, and one for the advertiser’s own ID. Each accepts several names separated by commas, so one setting covers all your advertisers.

Fill this in before you go live rather than after. Without it every callback comes back as a 404, and there is nothing in that response to suggest the parameter name is what is wrong.

Using what arrived

Everything from the call is available to the nodes after the Webhook, split into four parts:

• body, what they posted
• queries, the query parameters in the URL
• headers, the request headers
• cookies, any cookies they sent

Branch on it the same way you would on a response. A callback often carries several kinds of event, so read the field that says which one it is and give each its own connection. Anything you do not recognise should have a path too, otherwise the run ends there.

The data stays available for 180 days.

Retrying

A webhook that never arrives is common enough to plan for. The usual pattern gives it a second chance rather than giving up:

Webhook  →  nothing useful  →  Breaker  →  Wait  →  back to Webhook

See Breaker and Wait.

Starting a scenario with a webhook

A Webhook node can also be the first node in a scenario, rather than a pause inside one. Then it is not waiting for anything in particular, it just runs whenever the URL is called.

That is how you handle an advertiser who sends updates on their own schedule, without a lead of yours waiting for them.

Common mistakes

• Holding the line open when the advertiser takes minutes. The customer leaves long before the answer arrives.
• No check that the data actually came. In released mode a timeout looks exactly like a successful call to the nodes that follow.
• Not storing {external_id}, so their call has nothing to match against.
• Their parameter names not registered, so every call comes back as a 404.
• Changing the webhook ID and not telling the advertiser.