Webhooks
Instead of fetching updates for tracking, batch labels, and transactions manually, you can use Shippo webhooks to get notified when a status changes.
Setting up and testing webhooks
You can set up webhooks on the Shippo API Portal. This page also allows you to test webhooks with a sample payload.
note
The URL you set when creating your webhook must be less than 200 characters long.
We also offer a Webhooks API to allow you to programmatically create, retrieve, edit and delete webhooks. You can access the documentation here. The Webhooks API is currently in beta and the endpoints might change. Please reach out to support@shippo.com if you have questions.
note
When you purchase a label in Shippo, Shippo automatically creates a webhook for tracking that label. You can view the details of that webhook in the Shippo API Portal or using the webhooks endpoint.
Webhook event types
-
transaction_created: sent whenever a transaction is created in your account. The POST request body will contain a JSON of the Transaction object that was created. -
transaction_updated: sent whenever a transaction is updated in your account. The POST request body will contain a JSON of the Transaction object that was updated. -
track_updated: for tracking status updates. The POST request body will contain a JSON of the Tracking object . If you are interested in the types of events returned within the track_updated field, please view more details here .- We regularly request updates from each carrier's system to get the latest status of shipments. Whenever there's a change in status, we immediately send an update to the webhook via a POST request. The frequency of these updates varies among carriers due to the rate limits set by each carrier. On average, users can expect updates within 2 hours of an event occurring. For some carriers this time is much lower.
- For API version 2017-03-29 and older, the body will contain the Transaction object if the label was created on Shippo.
-
batch_created: for creating the Batch object that contain Batch Shipments. This process is done asynchronously, so first you'd get an empty Batch object back, then Batch Shipments will be created in the background. -
batch_purchased: for purchasing Batch Shipments through the Batch endpoint. This request is done asynchronously as well. Once purchases are complete, you will be able to download a merged PDF containing up to 100 labels per file. -
all: sent when any of the supported events occur. Acts as a catch-all for events.
Additionally, the Shippo-API-Version header is included in all webhook responses to indicate what version of the API is being used.
Webhook payload
The following are example webhook payloads for each webhook event type.
track_updatedbatch_purchasedbatch_createdtransaction_createdtransaction_updated
{
"event": "track_updated",
"test": true,
"data": {
"address_from": {
"city": "Las Vegas",
"country": "US",
"state": "NV",
"zip": "89101"
},
"address_to": {
"city": "Las Vegas",
"country": "US",
"state": "NV",
"zip": "89101"
},
"carrier": "usps",
"eta": "2019-08-24T14:15:22Z",
"messages": [
"string"
],
"metadata": "Order 000123",
"original_eta": "2021-07-23T00:00:00Z",
"servicelevel": {
"name": "Priority Mail Express",
"terms": "string",
"token": "usps_priority_express",
"extended_token": "string",
"parent_servicelevel": {
"name": "Priority Mail Express",
"terms": "string",
"token": "usps_priority_express",
"extended_token": "string"
}
},
"tracking_history": [
{
"location": {
"city": "Las Vegas",
"country": "US",
"state": "NV",
"zip": "89101"
},
"object_created": "2019-08-24T14:15:22Z",
"object_id": "string",
"object_updated": "2019-08-24T14:15:22Z",
"status": "DELIVERED",
"substatus": {
"code": "information_received",
"text": "Information about the package received.",
"action_required": true
},
"status_date": "2016-07-23T00:00:00Z",
"status_details": "Your shipment has been delivered at the destination mailbox."
}
],
"tracking_number": "9205590164917312751089",
"tracking_status": {
"location": {
"city": "Las Vegas",
"country": "US",
"state": "NV",
"zip": "89101"
},
"object_created": "2019-08-24T14:15:22Z",
"object_id": "string",
"object_updated": "2019-08-24T14:15:22Z",
"status": "DELIVERED",
"substatus": {
"code": "information_received",
"text": "Information about the package received.",
"action_required": true
},
"status_date": "2016-07-23T00:00:00Z",
"status_details": "Your shipment has been delivered at the destination mailbox."
},
"transaction": "string"
}
}{
"event": "batch_purchased",
"test": true,
"data": "batch # processing complete"
}{
"event": "batch_created",
"test": true,
"data": "batch # created"
}{
"event": "transaction_created",
"test": true,
"data": {
"commercial_invoice_url": "string",
"created_by": {
"first_name": "Shwan",
"last_name": "Ippotle",
"username": "shippotle@shippo.com"
},
"eta": "string",
"label_file_type": "PDF_4x6",
"label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
"messages": [
{
"source": "UPS",
"code": "carrier_timeout",
"text": "UPS API did not respond. Please try again in a few minutes."
}
],
"metadata": "string",
"object_created": "2019-08-24T14:15:22Z",
"object_id": "915d94940ea54c3a80cbfa328722f5a1",
"object_owner": "shippotle@shippo.com",
"object_state": "VALID",
"object_updated": "2019-08-24T14:15:22Z",
"parcel": "e94c7fdfdc7b495dbb390a28d929d90a",
"qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
"rate": {
"amount": "5.5",
"amount_local": "5.5",
"currency": "USD",
"currency_local": "USD",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"provider": "USPS",
"carrier_account": "078870331023437cb917f5187429b093",
"servicelevel_name": "Priority Mail",
"servicelevel_token": "fedex_ground"
},
"status": "SUCCESS",
"test": true,
"tracking_number": "9499907123456123456781",
"tracking_status": "DELIVERED",
"tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}
}{
"event": "transaction_updated",
"test": true,
"data": {
"commercial_invoice_url": "string",
"created_by": {
"first_name": "Shwan",
"last_name": "Ippotle",
"username": "shippotle@shippo.com"
},
"eta": "string",
"label_file_type": "PDF_4x6",
"label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
"messages": [
{
"source": "UPS",
"code": "carrier_timeout",
"text": "UPS API did not respond. Please try again in a few minutes."
}
],
"metadata": "string",
"object_created": "2019-08-24T14:15:22Z",
"object_id": "915d94940ea54c3a80cbfa328722f5a1",
"object_owner": "shippotle@shippo.com",
"object_state": "VALID",
"object_updated": "2019-08-24T14:15:22Z",
"parcel": "e94c7fdfdc7b495dbb390a28d929d90a",
"qr_code_url": "https://shippo-delivery.s3.amazonaws.com/96_qr_code.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
"rate": {
"amount": "5.5",
"amount_local": "5.5",
"currency": "USD",
"currency_local": "USD",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"provider": "USPS",
"carrier_account": "078870331023437cb917f5187429b093",
"servicelevel_name": "Priority Mail",
"servicelevel_token": "fedex_ground"
},
"status": "SUCCESS",
"test": true,
"tracking_number": "9499907123456123456781",
"tracking_status": "DELIVERED",
"tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}
}Expected webhook behavior
Shippo expects your Webhook endpoint to return a 2XX HTTP status code in a timely manner (three seconds or less) to indicate that the POST payload has been received. If your Webhook endpoint does not process the payload in a timely manner or you return a 408, 429, or 5XX status code, Shippo will retry twice. No retry is attempted upon other client error status codes (4XX).