Synchronous and asynchronous tracking
Safecube offers two ways to get container tracking data: the Container Tracking API, a synchronous API where your application requests the data, and the Webhooks API, an asynchronous API where Safecube sends the data to your application. The right choice depends on your use case, your traffic volume and your response time requirements.
Container Tracking API: synchronous pull
With a synchronous API, the client sends a request and waits for the server to process it and answer before continuing. This is a pull mechanism: the client pulls the information from the server on demand.
How the Container Tracking API works
- Your application requests the data of a specific shipment from the Container Tracking API.
- The server processes the request and returns the data as soon as possible.
- Your application waits for the response before its next action.
When the Container Tracking API fits
- Testers and small users — low traffic, or an occasional check of container statuses.
- Simple queries — specific, up-to-date data needed on demand.
Strengths and limits of the Container Tracking API
Strengths:
- Immediate response — the data comes back as soon as the request is processed.
- Easy to implement — suited to low-complexity applications.
- Good for small loads — works well while the number of requests stays manageable and longer response times are acceptable.
Limits:
- Long response times — with many requests or large datasets, response times grow and slow the whole process down.
- Polling is on the client — to get updates, your application has to keep sending requests to check for new data.
Webhooks API: asynchronous push
With an asynchronous API, the server sends information to the client when an event occurs. This is a push model: the client does not poll; the server pushes new data to the client as soon as it is available.
How the Webhooks API works
- Your application exposes an endpoint that receives updates from the Webhooks API.
- When a specific event occurs, such as a container status change or a shipment delay, Safecube pushes the relevant data to that endpoint.
- Your application processes the data asynchronously, without requesting it.
When the Webhooks API fits
- High loads — large users or high-traffic systems that constant polling of a synchronous API would slow down.
- Long response times — when the Container Tracking API responds slowly for your application, the Webhooks API removes the wait.
- Shipping line unavailability — when the shipping lines you track often experience disruptions, the Webhooks API sends up-to-date data as soon as the connection is back to normal.
- Advanced features — the Webhooks API also detects and notifies delays in container shipments, without manual polling.
Strengths and limits of the Webhooks API
Strengths:
- Lower load on client and server — updates are pushed only when necessary, which removes the overhead of continuous polling.
- Large volumes handled efficiently — suited to high-traffic applications and to users who need frequent updates.
- Automatic event notifications — your application is notified of important events, such as delays.
Limits:
- Setup complexity — more setup than a simple request-response model.
- Event-driven — data is sent only when events occur, which does not fit cases that need immediate access to data unrelated to an event.
Which API to choose
Choose the Container Tracking API (synchronous) when:
- you are a tester or a small user with relatively few API requests;
- you need data on demand and can wait for the response;
- your traffic is low and you expect no performance issue due to load.
Choose the Webhooks API (asynchronous) when:
- the Container Tracking API responds slowly for your application;
- you handle large volumes of data or frequent requests that could overwhelm a synchronous API;
- you need automatic event notifications, such as shipment delays;
- your application needs higher efficiency and a lower server load.
For larger applications with performance concerns, Safecube recommends moving to the Webhooks API to reduce overhead and improve responsiveness. The Getting started with webhooks page shows how to set it up.