Status & Image APIs with Webhook Calls

In addition to real-time RESTful calls, you can use Liminal’s Status & Image API webhooks to receive proactive shipment status and images from your carriers.   

• Get Delivery Status returns a shipment’s current status as provided by the carrier. Common statuses include “In Transit”, “Out for Delivery”, “Images Available”, “Images Complete”, or “Delivered”. 
• Get Expected Delivery Date returns a shipment’s expected or actual delivery date as provided by the carrier.  
• Get Bill of Lading returns an image (pdf, png, jpg) of the Bill of Lading (BOL) provided to the carrier when a shipment was tendered.
• Get Proof of Delivery returns an image of the Proof of Delivery (POD) confirming the shipment was delivered. The POD often (but not always) includes the name and signature of the person who signed for a shipment.  

Webhook Delivery Options 

Liminal’s webhooks offer both URL and email delivery options.  URLs and email addresses must be on your company’s domain or a subdomain for security purposes.   

A note on Security 

When you register a webhook, we keep a temporary copy of your credentials, encrypted in a way that only the specific webhook runner can decrypt. We combine this with your provided SCAC and reference number to perform /status checks, and possibly later image and document requests. 

Timing 

After you register a PRO/Tracking number or BOL, Liminal will check for updates about once an hour between 6AM Eastern and 10PM Pacific, sending any changes through your chosen delivery method. Liminal will continue to check for updates until any one of the following conditions are met: 

• You have made a request to https://api.liminalnetwork.com/<webhook_id>/cancel 
• Your chosen /status response has occurred (if you wanted DELIVERED, and /status returned DELIVERED, then we would stop on DELIVERED)
• The /status response is something that Liminal considers to be “final”, and unlikely to change; like DELIVERED, DELIVERED_MISSING, IMAGES_COMPLETE, or similar (any response involving DELIVERED or COMPLETE). 
• 21 Calendar days have passed (if you set a webhook up at 1PM on the 1^st, the webhook could run until 1PM on the 21^st, plus or minus an hour for DST if that changes) 

API Arguments 

• https://api.liminalnetwork.com/<carrier_id>/webhook 
• auth - authentication argument, required if not provided in the http headers
• email – Email address to send the results to; must be the same domain / subdomain as the registered company. USE ONE OF email OR webhook 
• webhook – HTTP(s) address to POST the results to; must be the same domain / subdomain as the registered company. USE ONE OF email OR webhook 
• bol - Bill of Lading number, typically used with /lading 
• pro - Pro / tracking number, can typically be used with all endpoints 
• status – One or more comma-separated status messages that can be returned from the carrier that can include: COMPLETED, COMPLETED_MISSING, IN_TRANSIT, IMAGES_COMPLETE, any status that the carrier may include, or any to receive any status changes as they happen 
• On success, returns: {“webhook_id”: “<webhook_id>”} 

• /<webhook_id>/cancel
• HTTPS GET will cancel the webhook 

• /<webhook_id>/lading and /<webhook_id>/proof
• image - 0..pages-1, when /lading and /proof can return multiple pages, fetch individual pages in the highest quality we have. 
• dl – when fetching images, if dl is in the list of arguments with any value, we will include the Content-Disposition HTTP header for browsers to automatically download the file with a default filename. 

For more information 

For a step-by-step how-to, visit How to Use Webhooks.