Tracking Webhook API
Mutation.registerTrackWebhook allows you to get a callback to the URL registered by the user when a waybill status change occurs.
Basic procedure
Register & Unregister
Register
To start tracking for a waybill, you must first register
carrierId, trackingNumber, callbackUrl, and expirationTime using [Mutation.registerTrackWebhook] (/docs/api-schema/api/mutations/register-track-webhook).
If you don't know the carrierId, please read the Tracking API documentation first.
For callbackUrl, please enter the server URL of the user who wants to receive a response when the status of the waybill changes. Forward the request from the DeliveryTracker to that URL.
The expirationTime follows the ISO8601 standard, and it is generally recommended to use a time 48 hours after the current time.
For more information, see "Webhook Keep Alive" in this article.
If you test through the Try Run button above, you won't be able to debug in the Console because you won't be connected to the user's project. You must write separate client code to call HTTP Request after authentication to debug in Console.
Unregister
You can explicitly unregister a webhook by passing a current time rather than a future time to the expirationTime in Mutation.registerTrackWebhook.
However, rather than explicitly unregistering by making API calls like this, it is recommended to automatically delete via TTL expiration. For more information, see the "Webhook Keep Alive" part of this article.
Implementing a Callback Handler
When the DeliveryTracker Webhook system detects a change in the waybill, it sends the following request to the registered Callback URL.
POST {callbackUrl}
content-type: application/json
{
"carrierId": "{carrierId}",
"trackingNumber": "{trackingNumber}"
}
Only carrierId and trackingNumber are passed to the callback,
Based on this information, you can use Query.track to retrieve the information you want.
Typical implementations
You can choose one of two implementation methods to implement the Callback Handler to suit your situation.
Method 1. Processing via Callback Queue
We recommend putting the TrackingNumber in a separate Queue within the Callback Handler, and calling Query.track from a separate Worker that reads the TrackingNumber accumulated in the Queue.
Method 2. Calling Query.track directly from within a Callback Handler
If queuing is not feasible for your situation, you can also call Query.track directly from within the Callback Handler. However, while this approach is easy to implement, it can increase the complexity of Timeout and RateLimit relative to implementation method 1 in high traffic cases.
Callback Response Code & Retry
It is recommended that Callback implementations deliver the response within one second and send 202 (Accepted) as the Response Status Code.
If the HTTP Response Status Code of the Callback Url is not 2XX, the internal Exponential Backoff Retry logic will continue to retry until expirationTime is reached.
To avoid continually getting callback errors or having the expirationTime expire due to a short expirationTime, update the expirationTime periodically. For more information, see Webhook Keep Alive.
Webhook Keep Alive
If you have a waybill number that you want to track, we recommend using a future time 48 hours after the current time as the expirationTime and updating the expirationTime periodically (every 24 hours).
For a list of waybill numbers that should continue to be tracked once every 24 hours, we recommend calling Mutation.registerTrackWebhook again (with expirationTime set to the current time + 48 hours).
This allows audiences that should continue to be tracked to have their expirationTime incremented, and those that are no longer tracked to be automatically unenrolled after 48 hours.
You can use this approach to avoid sending the wrong order of register and unregister and unintentionally unregistering or remaining in the register state forever.
Testing
Waiting for the change to occur on the actual waybill is quite time consuming (n hours to n days).
An alternative is to use [Dummy Tracking Number] (/docs/dummy-tracking-number).
To reduce this time, in the Delivery Tracker Console, in the "Webhooks" menu within a project, you can request a callback call to the callback call queue by clicking the "Callback Call Test Trigger" button with the list of registered webhooks and the "Callback Call Test Trigger" button.
These callbacks are typically processed within n minutes and are sent out even if the status of the waybill has not changed.
Notes
What are the advantages of using the Track Webhook over polling Query.track?
Delivery Tracker is designed to work efficiently based on internal optimization logic.
For example, in a typical case, if you call Query.track immediately after a callback occurs, the tracking data is cached and can be used with lower latency than if you poll Query.track. In addition, you don't have to worry about various situations that may occur during polling, such as polling cycles, and you can use Rate Limit efficiently by reducing the frequency of Track API calls by calling the Track API only when a callback occurs.
Are callbacks guaranteed to occur?
As long as the expirationTime is not reached, a callback is guaranteed to occur if the status of the waybill changes. (The callback also occurs at first initialization). Retries periodically based on internal retry logic.
If you do not succeed by the expirationTime, it may never be sent and will be deleted, so be careful to manage the expirationTime. For more information, see "Webhook Keep Alive".
Please note the API Rate Limit.
Please note the API Call Rate Limit given to your project.
Queue it up and use it.
Rather than implementing the track api call within a callback, we recommend that you pass the change to a separate queue in the callback and process it in a separate worker.
Depending on the situation, an event can occur even if no changes are made.
In some situations, such as internal hash changes, events can occur even if no changes are made.
The behavior of the Callback Url should be designed with the assumption that data can be manipulated and sent to the Callback Url from servers other than the Delivery Tracker server.
Anyone with the information in the Callback Url can call it, so you can't trust that the data is coming from the Delivery Tracker server.
If you're looking for authentication, such as HMAC, please contact us.
When developing Callbacks, do not take steps to allow only the IP Address of the Delivery Tracker Webhook server.
The IP Address used to call the Callback Url in Delivery Tracker can change at any time.