Webhooks against polling is usually argued as a general engineering question. In freight it is not general, because the object being tracked is a truck: it moves for days, it goes quiet in tunnels and border queues, and its position changes continuously while its status changes about a dozen times in total. Those two data types want opposite patterns, which is why a road freight visibility API almost always ends up exposing both.
The decision is not which pattern is better. It is which of your two feeds goes on which.
The two patterns, briefly
Polling means your system asks. On a timer, it calls an endpoint and receives the current state of a load or a list of loads. You control the cadence, you control the load on your own infrastructure, and you learn about a change on average half a cycle after it happened.
Webhooks mean the platform tells you. When something changes, it posts a payload to an HTTPS endpoint you host. You learn about the change in seconds, and in exchange you now operate a public endpoint that has to be available, authenticated and idempotent.
The trade is latency against operational surface. Polling puts the burden inside your perimeter, webhooks move some of it to the boundary.
What it costs when the object is a truck
The arithmetic is worth doing rather than assuming, because it points in different directions for the two feed types.
Take five hundred active loads. Polling each one every five minutes is 144,000 calls a day. Every minute, 720,000. Those loads produce roughly twelve meaningful status events each over a two-day cycle, so around 3,000 status events a day reach you. For milestones, webhooks are not marginally cheaper, they are two orders of magnitude cheaper, and they arrive first.
Now take position. A telematics box reports every two to fifteen minutes depending on the provider, the contract and whether the ignition is on. Five hundred trucks at a two-minute cadence generate 360,000 position updates a day, and pushing each one individually as a webhook is worse than useless: it creates a delivery, a retry policy and an acknowledgement for a data point that is superseded two minutes later.
Hence the split that experienced integrations converge on. Status changes go on webhooks because they are rare, ordered and each one matters. Position goes on a pull, either a periodic batch of the current fleet snapshot or a query at the moment a human opens a map. Nobody needs a position they are not looking at.
Retries, duplicates and the idempotency key
Every webhook system retries, because the alternative is losing events when a receiver blinks. Retries mean duplicates, and duplicates in freight data are not cosmetic: a second arrival event recorded against the same stop doubles the dwell and corrupts detention, on-time performance and every number derived from them, as listed in the guide to road freight KPIs.
The fix is an idempotency key, and it has to be built from the event rather than from the delivery. A key made of shipment reference, event type and event timestamp makes a replay harmless. A key made of the delivery identifier does not, because a retry carries a new delivery identifier for the same fact.
Two related rules follow. Store the raw payload before you process it, so a mapping bug is replayable rather than a permanent loss. And order events by event time rather than receipt time: retries and parallel delivery routinely land a departure before the arrival it follows, and a state machine that trusts arrival order will record impossible sequences.
What happens when your endpoint is down
This is the question that decides whether a webhook integration survives its first bad week.
Find out three things before you build against any push feed. How many times does the sender retry and with what backoff. How long does it keep an undelivered event before dropping it. And is there a replay or catch-up endpoint that lets you ask for everything between two timestamps after an outage.
If the answer to the third is no, you need a reconciliation poll regardless: a low-frequency sweep, perhaps hourly, that fetches current state for all active loads and repairs anything the push feed lost. That sweep is cheap, it is the safety net that makes the whole architecture trustworthy, and it is the piece most first integrations skip.
Two more boundary requirements, both non-negotiable. Verify the signature on every inbound call, since an unauthenticated public endpoint accepting delivery events is an invitation to write false arrivals into your own records. And acknowledge fast: accept the payload, queue it, return 200. Doing the mapping work inside the request handler means a slow database turns into sender-side timeouts, which turn into retries, which make the slowness worse.
Where polling is still the right answer
Four cases, and they are common rather than exotic.
- No public endpoint. Plenty of shippers cannot expose an inbound HTTPS endpoint without a security review measured in months. Polling ships this quarter.
- Continuous streams. Position, temperature on a reefer, fuel level. Values that are always changing and only matter when read.
- Batch-shaped downstream work. If the consuming process is a nightly reconciliation or an invoice run, event-level latency buys nothing.
- The reconciliation sweep. Even in a webhook-first design, described above, and the reason the two patterns are not alternatives in practice.
The hybrid nearly everyone lands on
The shape that holds up in production has four parts: webhooks for status changes and exceptions, a pull for position and other continuous values, an hourly reconciliation sweep against active loads, and one normalised internal event model that both paths write into so no downstream consumer needs to know which path a fact arrived on.
That last part matters more than the transport choice. The same normalisation requirement appears when a carrier can only send files, which is the subject of the comparison of API and EDI channels in road freight, and it is what keeps a mixed estate from producing two versions of the truth.
Judge the result on one number: the share of active loads whose last event is older than your expected reporting interval. If that share is stable and small, the integration works, whichever pattern delivered the events. If it drifts upward, something stopped sending and no amount of architecture will tell you which pattern was at fault, only the reconciliation sweep will. Where the underlying feed itself is unreliable, the problem is usually upstream of the transport entirely, as covered in the piece on visibility against tracking and in the broader question of who operates the flows, set out in the guide to 3PL and 4PL models.
